@@ -0,0 +1,16 @@
+---
+'@objectstack/cli': patch
+---
+
+fix(cli): a flag given without its value (`os dev -d`) now opens with the INVOCATION ERROR line
+
+Clause-②: no
+Metadata-protocol: none
+
+`os dev -d`, `os serve --port` and `os migrate meta --from` used to exit 2 with only oclif's `Error: Flag --NAME expects a value` line. Backgrounded, that reads like a server that booted and died. The CLI now writes its one-line `objectstack: INVOCATION ERROR — … The command never ran: nothing was started and nothing is listening.` first, as it already did for an unknown flag or a refused value.
+
+The same line now also leads three other parse failures that oclif raises the same way: a flag with an option list given without its value (`os dev --log-level`), a single-valued flag given twice (`os dev -p 1 -p 2`), and a value a flag's own parser refused (`os lint --eval-min abc`).
+
+Nothing else changes: the same inputs are accepted and refused, the exit code is still 2, and oclif's own lines follow unchanged. A command that parsed and then failed while running gets no banner.
+
+The banner's reason now carries oclif's whole message on one line instead of only its first line, so `os plugin keygen` reads `The following error occurred: Missing required flag out` and `os lint --eval-min abc` reads `Parsing --eval-min; Expected an integer but received: abc` where both used to name only the header.
@@ -24,7 +24,7 @@ import { mkdirSync, mkdtempSync, rmSync, symlinkSync, writeFileSync } from 'node
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { Flags, Parser } from '@oclif/core';
+import { Args, Command, Errors, Flags, Parser } from '@oclif/core';
 
 import { CLI_NAME } from './format.js';
 import {
@@ -54,6 +54,50 @@ async function realNonExistentFlagError(): Promise<unknown> {
   throw new Error('the parser accepted --no-ui: this fixture no longer reproduces the measured failure');
 }
 
+/**
+ * Whatever the REAL parser throws for `argv` against `input` — the shared shape
+ * of the parse-time cases below. Every one of them is thrown through
+ * `Parser.parse`, the public entry point, for the same reason as
+ * {@link realNonExistentFlagError}: the predicate is only worth anything against
+ * what oclif actually throws.
+ */
+async function realParseFailure(argv: string[], input: Parameters<typeof Parser.parse>[1]): Promise<unknown> {
+  try {
+    await Parser.parse(argv, { strict: true, ...input });
+  } catch (error) {
+    return error;
+  }
+  throw new Error(`the parser accepted ${JSON.stringify(argv)}: this fixture no longer reproduces a parse failure`);
+}
+
+/**
+ * A command that PARSED fine and then failed in its own body with
+ * `this.error()` — the commonest runtime failure in this CLI. oclif gives it
+ * the same class, the same own fields and the same exit 2 as the parse-time
+ * `CLIError`s, which is why the predicate cannot read any of those.
+ */
+async function realRuntimeCommandError(): Promise<unknown> {
+  class RanAndFailed extends Command {
+    static override flags = { database: Flags.string({ char: 'd' }) };
+    async run(): Promise<void> {
+      await this.parse(RanAndFailed);
+      this.error('objectstack.config.ts not found');
+    }
+  }
+  // A bare oclif root: loading this package's own config would import every
+  // command module, ~5 s for one fixture.
+  const root = fixtureDir();
+  writeFileSync(join(root, 'package.json'), JSON.stringify({ name: 'fixture', version: '0.0.0', oclif: {} }));
+  try {
+    await RanAndFailed.run(['-d', 'file.db'], { root });
+  } catch (error) {
+    return error;
+  } finally {
+    rmSync(root, { force: true, recursive: true });
+  }
+  throw new Error('the command did not fail: this fixture no longer reproduces a runtime failure');
+}
+
 function fixtureDir(): string {
   const dir = mkdtempSync(join(tmpdir(), 'os-invocation-'));
   return dir;
@@ -165,6 +209,65 @@ describe('[#10111] isInvocationError', () => {
     expect(isInvocationError(await realNonExistentFlagError())).toBe(true);
   });
 
+  // The parse failures oclif raises as a PLAIN `CLIError` from inside its
+  // parser — no `parse` / `showHelp` fields — measured on `os dev -d`,
+  // `os serve --port`, `os migrate meta --from`, `os dev --log-level`,
+  // `os dev -p 1 -p 2` and `os lint --eval-min abc`: each exited 2 with no banner.
+  it('recognises a flag given without its value (`os dev -d`)', async () => {
+    const error = await realParseFailure(['-d'], { flags: { database: Flags.string({ char: 'd' }) } });
+    expect(String((error as Error).message)).toBe('Flag --database expects a value');
+    expect(isInvocationError(error)).toBe(true);
+  });
+
+  it('recognises a flag with an option list given without its value (`os dev --log-level`)', async () => {
+    const error = await realParseFailure(['--log-level'], {
+      flags: { 'log-level': Flags.string({ options: ['debug', 'info'] }) },
+    });
+    expect(isInvocationError(error)).toBe(true);
+  });
+
+  it('recognises a single-valued flag given twice (`os dev -p 1 -p 2`)', async () => {
+    const error = await realParseFailure(['-p', '1', '-p', '2'], { flags: { port: Flags.string({ char: 'p' }) } });
+    expect(isInvocationError(error)).toBe(true);
+  });
+
+  it('recognises a value the flag’s own parser refused (`os lint --eval-min abc`)', async () => {
+    const error = await realParseFailure(['--eval-min', 'abc'], { flags: { 'eval-min': Flags.integer() } });
+    expect(isInvocationError(error)).toBe(true);
+  });
+
+  // The other classes the parser raises at the same place already carry the
+  // `CLIParseError` fields and printed the banner before; pinned so the
+  // reading keeps covering them.
+  it('recognises a missing required flag, a missing required arg and an unexpected arg', async () => {
+    const required = await realParseFailure([], { flags: { out: Flags.string({ required: true }) } });
+    const missingArg = await realParseFailure([], { args: { id: Args.string({ required: true }) } });
+    const extraArg = await realParseFailure(['a', 'b'], { args: { id: Args.string({ required: true }) } });
+    expect(isInvocationError(required)).toBe(true);
+    expect(isInvocationError(missingArg)).toBe(true);
+    expect(isInvocationError(extraArg)).toBe(true);
+  });
+
+  it('does not claim a command that parsed and then failed — same class, fields and exit 2 as a parse failure', async () => {
+    const runtime = await realRuntimeCommandError();
+    const parseTime = await realParseFailure(['-d'], { flags: { database: Flags.string({ char: 'd' }) } });
+    // The measured reason the predicate cannot read the error's class or fields.
+    expect((runtime as Error).constructor).toBe((parseTime as Error).constructor);
+    expect(Object.getOwnPropertyNames(runtime).sort()).toEqual(Object.getOwnPropertyNames(parseTime).sort());
+    expect((runtime as { oclif?: unknown }).oclif).toEqual({ exit: 2 });
+    expect(isInvocationError(runtime)).toBe(false);
+  });
+
+  it('does not claim a bare `Errors.error()` thrown outside the parser', () => {
+    let thrown: unknown;
+    try {
+      Errors.error('ECONNREFUSED 127.0.0.1:3000');
+    } catch (error) {
+      thrown = error;
+    }
+    expect(isInvocationError(thrown)).toBe(false);
+  });
+
   it('does not claim an ordinary runtime failure', () => {
     expect(isInvocationError(new Error('ECONNREFUSED 127.0.0.1:3000'))).toBe(false);
     expect(isInvocationError(undefined)).toBe(false);
@@ -185,6 +288,52 @@ describe('[#10111] invocationFailureLine', () => {
     expect(line).toContain(`Invoked as: ${INVOCATION_PREFIX} dev --no-ui`);
   });
 
+  it('names the flag that is missing its value (`os dev -d`)', async () => {
+    const error = await realParseFailure(['-d'], { flags: { database: Flags.string({ char: 'd' }) } });
+    const line = invocationFailureLine(error, ['dev', '-d']);
+    expect(line).toBeDefined();
+    expect(line!.startsWith(`${INVOCATION_PREFIX}: INVOCATION ERROR — Flag --database expects a value. `)).toBe(true);
+    expect(line).toContain(`Invoked as: ${INVOCATION_PREFIX} dev -d`);
+  });
+
+  // oclif spreads these reasons over several lines under a generic header; the
+  // banner used to keep only the header ("The following error occurred:.",
+  // "Parsing --eval-min.") and so named no reason at all.
+  it('names the missing required flag, not only oclif’s header (`os plugin keygen`)', async () => {
+    const error = await realParseFailure([], { flags: { out: Flags.string({ char: 'o', required: true }) } });
+    expect(String((error as Error).message).split('\n')[0]).toBe('The following error occurred:');
+    const line = invocationFailureLine(error, ['plugin', 'keygen']);
+    expect(line).toContain('INVOCATION ERROR — The following error occurred: Missing required flag out. The command never ran');
+  });
+
+  it('names the value a flag’s parser refused, not only `Parsing --X` (`os lint --eval-min abc`)', async () => {
+    const error = await realParseFailure(['--eval-min', 'abc'], { flags: { 'eval-min': Flags.integer() } });
+    const line = invocationFailureLine(error, ['lint', '--eval-min', 'abc']);
+    expect(line).toContain('INVOCATION ERROR — Parsing --eval-min; Expected an integer but received: abc. The command never ran');
+  });
+
+  it('keeps a joined reason on one line, free of colour codes and of the help tail', async () => {
+    const error = await realParseFailure([], { args: { id: Args.string({ description: 'The installed plugin id', required: true }) } });
+    const line = invocationFailureLine(error, ['plugin', 'uninstall']);
+    expect(line).toContain('INVOCATION ERROR — Missing 1 required arg: id The installed plugin id. The command never ran');
+    expect(line).not.toContain('\n');
+    expect(line).not.toContain('See more help');
+    const dimmed = Object.assign(new Error('The following error occurred:\n  \u001b[2mMissing required flag out\u001b[22m'), { parse: {}, showHelp: false });
+    expect(invocationFailureLine(dimmed, ['plugin', 'keygen'])).toContain('occurred: Missing required flag out. The command');
+    expect(invocationFailureLine(dimmed, ['plugin', 'keygen'])).not.toContain('\u001b');
+  });
+
+  it('caps a long joined reason so the line cannot run on', () => {
+    const long = Object.assign(new Error(`Missing 9 required args:\n${'an argument with a long description\n'.repeat(20)}`), { parse: {}, showHelp: true });
+    const line = invocationFailureLine(long, ['plugin', 'uninstall']);
+    expect(line).toContain('.... The command never ran');
+    expect(line!.length).toBeLessThan(450);
+  });
+
+  it('returns undefined for a command that parsed and then failed', async () => {
+    expect(invocationFailureLine(await realRuntimeCommandError(), ['dev', '-d', 'file.db'])).toBeUndefined();
+  });
+
   it('drops oclif’s `See more help with --help` tail, which is the second line of the message', async () => {
     const error = await realNonExistentFlagError();
     expect(String((error as Error).message)).toContain('See more help with --help');
 
@@ -133,31 +133,88 @@ export function moduleEntryMisuseLines(selfPath: string, binPath: string): [stri
   ];
 }
 
+/**
+ * A stack frame inside `@oclif/core`'s parser module (`lib/parser/`), on
+ * either path separator.
+ */
+const OCLIF_PARSER_FRAME = /[\\/]@oclif[\\/]core[\\/]lib[\\/]parser[\\/]/;
+
 /**
  * Is this one of oclif's ARGUMENT errors — a failure that happened while
  * parsing the invocation, before the command ran at all?
  *
- * Structural rather than `instanceof`: `@oclif/core` does not export
- * `CLIParseError` (`lib/parser/errors.js` is not in the package's `exports`
- * map), and reaching into an unexported path to type-test would be a worse
- * coupling than reading two own properties its constructor always sets. The
- * corpus this is checked against is the REAL parser's output —
- * `invocation.test.ts` throws the errors through `Parser.parse`, the public
- * entry point, instead of hand-rolling look-alikes.
+ * Two readings, both structural, neither reading the English message:
+ *
+ *   1. `CLIParseError`'s own fields. Structural rather than `instanceof`:
+ *      `@oclif/core` does not export `CLIParseError` (`lib/parser/errors.js` is
+ *      not in the package's `exports` map), and reaching into an unexported
+ *      path to type-test would be a worse coupling than reading two own
+ *      properties its constructor always sets. This covers an unknown flag, a
+ *      refused option value, a missing required flag or arg and an unexpected
+ *      arg.
+ *   2. The THROW SITE. The parser also throws a plain `CLIError` — a flag given
+ *      without its value (`os dev -d`), a single-valued flag given twice, a
+ *      flag with an option list given bare — and passes a flag's own `parse`
+ *      failure (`Flags.integer` on `abc`) through. Those carry nothing a
+ *      runtime failure does not: a command that parsed and then called
+ *      `this.error()` throws the same class, with the same own fields and the
+ *      same `oclif.exit` of 2. What differs is where it was thrown, so the
+ *      error's own stack is read for a frame inside oclif's parser module. A
+ *      command body never runs with that module on the stack — `this.parse()`
+ *      has returned before it does.
+ *
+ * Reading (2) degrades towards silence: a stack it cannot read (a stack-trace
+ * limit of 0, a moved parser module) answers false, which is the behaviour
+ * before it existed, never a banner on a runtime failure. The moved-module
+ * case is caught by `invocation.test.ts`, which throws every case through the
+ * REAL parser's public entry point (`Parser.parse`) instead of hand-rolling
+ * look-alikes, and pins a real command's runtime `this.error()` as not
+ * claimed.
  */
 export function isInvocationError(error: unknown): boolean {
   if (!error || typeof error !== 'object') return false;
   const own = Object.prototype.hasOwnProperty;
   // Both are class fields on `CLIParseError`; `parse` alone would also match a
   // plain object that happens to carry parsed input.
-  return own.call(error, 'parse') && own.call(error, 'showHelp');
+  if (own.call(error, 'parse') && own.call(error, 'showHelp')) return true;
+  if (!(error instanceof Error)) return false;
+  const stack = error.stack;
+  return typeof stack === 'string' && OCLIF_PARSER_FRAME.test(stack);
 }
 
-/** The first line of a message, with oclif's `See more help with --help` tail dropped. */
+/** oclif's closing line on every parse error, which says nothing about this one. */
+const HELP_TAIL = 'See more help with --help';
+
+/** SGR colour codes: oclif dims the reasons it lists under a header when stderr is a terminal. */
+const ANSI_SGR = /\u001b\[[0-9;]*m/g;
+
+/** Longest reason the banner echoes, so a long argument list cannot push the line into a wrap. */
+const REASON_MAX = 200;
+
+/**
+ * oclif's message as ONE line, with its `See more help with --help` tail and
+ * colour codes dropped.
+ *
+ * Several parse errors put a generic header on line one and the reason under
+ * it: `The following error occurred:` over `Missing required flag out`,
+ * `Parsing --eval-min` over `Expected an integer but received: abc`, `Missing
+ * 1 required arg:` over the arg list. Keeping line one alone left a banner that
+ * named no reason, so every line is kept, whitespace runs collapsed: a line
+ * after a header ending in `:` follows it after a space, any other after `; `.
+ */
 function reasonOf(error: unknown): string {
   const message = (error as { message?: unknown } | null)?.message;
-  const first = String(typeof message === 'string' ? message : '').split('\n')[0]?.trim() ?? '';
-  return first || 'invalid arguments';
+  const lines = String(typeof message === 'string' ? message : '')
+    .replace(ANSI_SGR, '')
+    .split('\n')
+    .map((line) => line.replace(/\s+/g, ' ').trim())
+    .filter((line) => line !== '' && line !== HELP_TAIL);
+  let reason = '';
+  for (const line of lines) {
+    reason = reason === '' ? line : `${reason}${reason.endsWith(':') ? ' ' : '; '}${line}`;
+  }
+  if (reason === '') return 'invalid arguments';
+  return reason.length > REASON_MAX ? `${reason.slice(0, REASON_MAX - 3)}...` : reason;
 }
 
 /** The invocation as typed, capped so one long argument cannot push the line into a wrap. */
 
@@ -93,6 +93,7 @@ let linkDir: string;
 let barrel: Run;
 let barrelViaSymlink: Run;
 let unknownFlag: Run;
+let missingValue: Run;
 let version: Run;
 
 beforeAll(async () => {
@@ -101,11 +102,12 @@ beforeAll(async () => {
   const link = join(linkDir, 'index.ts');
   symlinkSync(BARREL, link);
 
-  // Sequential on purpose: four cold tsx starts, each loading every command
+  // Sequential on purpose: five cold tsx starts, each loading every command
   // module, in a container several agents share.
   barrel = await runTsx([BARREL], dir);
   barrelViaSymlink = await runTsx([link], dir);
   unknownFlag = await runTsx([CLI, 'dev', '--no-ui'], dir);
+  missingValue = await runTsx([CLI, 'dev', '-d'], dir);
   version = await runTsx([CLI, '--version'], dir);
 }, RUN_TIMEOUT_MS);
 
@@ -168,6 +170,26 @@ describe('[#10111] an unknown flag on `dev`', () => {
   });
 });
 
+describe('[#28931] a flag given without its value on `dev`', () => {
+  // oclif throws this one as a plain `CLIError` from inside its parser, not a
+  // `CLIParseError`, so it used to exit 2 with oclif's one line and no banner.
+  it('keeps exit 2 and oclif’s own line', () => {
+    expect(missingValue.code).toBe(2);
+    expect(missingValue.stderr).toContain('Error: Flag --database expects a value');
+  });
+
+  it('puts the INVOCATION ERROR line FIRST on stderr', () => {
+    const line = firstLine(missingValue.stderr);
+    expect(line).toContain('objectstack: INVOCATION ERROR — Flag --database expects a value');
+    expect(line).toContain('The command never ran');
+    expect(line).toContain('Invoked as: objectstack dev -d');
+  });
+
+  it('keeps stdout empty', () => {
+    expect(missingValue.stdout).toBe('');
+  });
+});
+
 describe('[#10111] the success path the shims kept', () => {
   it('`--version` still exits 0 with the version on stdout and nothing added to stderr', () => {
     // The shims now inline what `execute()` did instead of calling it, so the