fix(cli): serve's boot-quiet window buffers plugin log lines instead of discarding them (#4012) (#4084)

`serve` blanks stdout while the kernel boots so the startup banner is readable,
and dropped what it intercepted. `ObjectLogger` routes debug/info/warn to stdout
and only error/fatal to stderr, so that one line swallowed every boot-phase
`logger.warn` any plugin emits — the ADR-0110 D5 `[action-governance]`
inventory, the automation engine's binding warnings, every degraded-boot notice.
`os dev` spawns `serve` with inherited stdio, so one drain blinded both
entrypoints at every log level, inverting the flag's own promise (the default is
`warn` precisely "so flow/hook execution failures surface", ADR-0032).

The window becomes a buffer rather than a drain:

- `BootLogCapture` is a line-oriented, bounded sink that classifies each
  intercepted line against ObjectLogger's pretty/text/json renderings and
  retains only records at warn or above, so buffer size tracks a boot's
  warnings rather than its chattiness.
- Retained records replay under the banner, and on the two exits that never
  reach it: OS_MIGRATE_AND_EXIT and serve's error path.
- `--verbose` / `--log-level debug|info` no longer open the window at all.

On examples/app-todo, `os serve` went from 25 lines with zero WARN to surfacing
five boot warnings including the `[action-governance]` line naming all eight
unbound actions. Same on `os dev`.

13 unit cases drive a real ObjectLogger through the real interception; 2 e2e
cases boot a real stack through bin/run-dev.js and read its stdout. Both e2e
cases fail against the pre-fix command.

Closes #4012

Author: os-zhuang

.changeset/serve-boot-log-visibility.md

@@ -0,0 +1,38 @@
+---
+'@objectstack/cli': patch
+---
+
+**`os dev` / `os serve` stop swallowing every plugin boot-phase log line — the
+boot-quiet window buffers instead of discarding (#4012).**
+
+`serve` blanks stdout while the kernel boots so the startup banner is readable,
+and dropped what it intercepted. `ObjectLogger` routes `debug`/`info`/`warn` to
+**stdout** — only `error`/`fatal` go to stderr — so that one line swallowed
+every boot-phase `logger.warn` any plugin emits: the ADR-0110 D5
+`[action-governance]` inventory, the automation engine's binding warnings,
+every degraded-boot notice. `os dev` spawns `serve` with inherited stdio, so a
+single drain blinded both entrypoints at every log level, and it inverted the
+flag's own promise — the default is `warn` precisely "so flow/hook execution
+failures surface (ADR-0032)". Data-phase logging was unaffected, which is why
+the hole survived: `--log-level debug` printed thousands of lines with none
+from boot.
+
+- The intercepted bytes now land in a line-oriented, bounded `BootLogCapture`
+  that classifies each line against `ObjectLogger`'s pretty/text/json
+  renderings and retains only records at `warn` or above, so buffer size tracks
+  a boot's warnings rather than its chattiness. The startup chatter the window
+  exists to hide is still dropped.
+- Retained records replay under the banner, beside the automation and seed
+  summaries that exist for exactly this reason — and on the two exits that
+  never reach the banner: `OS_MIGRATE_AND_EXIT` (a deploy pipeline must not
+  lose a degraded-boot warning) and serve's error path, where a boot that died
+  is when its warnings matter most.
+- `--verbose` / `--log-level debug|info` no longer open the window at all.
+  Buffering a stream the operator explicitly asked to watch would be the flag
+  defeating itself.
+
+On `examples/app-todo`, `os serve` went from 25 lines with zero WARN among them
+to surfacing five boot warnings, including the `[action-governance]` line
+naming all eight unbound actions. This closes the loop the D5 inventory
+changeset left open: the inventory was already emitted correctly and is now
+visible on the platform's own dev loop.

packages/cli/src/commands/serve.ts

@@ -15,6 +15,7 @@ import { PLATFORM_CAPABILITY_TOKENS } from '@objectstack/spec/kernel';
 import { missingProviderMessage } from '../utils/capability-preflight.js';
 import { resolveObjectStackHome } from '@objectstack/runtime';
 import { LOG_LEVELS, resolveLogLevel, readLogLevelEnv } from '../utils/log-level.js';
+import { BootLogCapture, isVerboseBootLevel } from '../utils/boot-log-capture.js';
 import { redactConnectionUrl, describeDriverConnection } from '../utils/connection-display.js';
 import {
   printHeader,
@@ -24,6 +25,7 @@ import {
   printStep,
   printInfo,
   printServerReady,
+  printBootDiagnostics,
   type AutomationReadySummary,
   type SeedSourceSummary,
 } from '../utils/format.js';
@@ -176,7 +178,7 @@ export default class Serve extends Command {
       options: ['minimal', 'default', 'full'],
     }),
     'log-level': Flags.string({
-      description: 'Kernel logger level. Defaults to $OS_LOG_LEVEL / $LOG_LEVEL, else `warn` so flow/hook execution failures surface (ADR-0032). Use `silent` to fully quiet the runtime.',
+      description: 'Kernel logger level. Defaults to $OS_LOG_LEVEL / $LOG_LEVEL, else `warn` so flow/hook execution failures surface (ADR-0032). Boot-phase warnings are replayed under the startup banner; `debug`/`info` stream the whole boot live instead. Use `silent` to fully quiet the runtime.',
       options: [...LOG_LEVELS],
     }),
     verbose: Flags.boolean({ char: 'v', description: 'Verbose output — shortcut for --log-level debug.' }),
@@ -554,11 +556,35 @@ export default class Serve extends Command {
     let resolvedDriverLabel: string | undefined;
     let resolvedDatabaseUrl: string | undefined;
 
+    // Resolve the kernel logger level up front. It decides more than the
+    // logger's own threshold: it decides whether the boot-quiet window below
+    // runs at all, so it has to be known BEFORE the window opens rather than
+    // at the `new Runtime(...)` call further down.
+    const bootLogLevel = resolveLogLevel({
+      verbose: flags.verbose,
+      flag: flags['log-level'],
+      envLevel: readLogLevelEnv(),
+    });
+    // `--verbose` / `--log-level debug|info` asks to watch the boot happen.
+    // Blanking stdout through it would be the flag defeating itself, so at
+    // those levels the window never opens and boot output streams live — the
+    // banner just prints at the end of it (#4012).
+    const verboseBoot = isVerboseBootLevel(bootLogLevel);
+
     // Save original console/stdout methods — we'll suppress noise during boot
     const originalConsoleLog = console.log;
     const originalConsoleDebug = console.debug;
     const origStdoutWrite = process.stdout.write.bind(process.stdout);
     let bootQuiet = false;
+    // Everything the quiet window intercepts lands here instead of being
+    // dropped on the floor, so boot-phase `logger.warn` survives to be
+    // replayed under the banner (#4012).
+    const bootLogs = new BootLogCapture();
+    /** Diagnostics to replay, or `undefined` when the boot had nothing to say. */
+    const collectBootDiagnostics = () => {
+      const lines = bootLogs.diagnostics();
+      return lines.length > 0 ? { lines, dropped: bootLogs.droppedCount } : undefined;
+    };
 
     const restoreOutput = () => {
       bootQuiet = false;
@@ -568,19 +594,34 @@ export default class Serve extends Command {
     };
 
     try {
-      // ── Suppress ALL runtime noise during boot ────────────────────
+      // ── Hold back runtime noise during boot ───────────────────────
       // Multiple sources write to stdout during startup:
       //   • Pino-pretty (direct process.stdout.write)
       //   • ObjectLogger browser fallback (console.log)
       //   • SchemaRegistry (console.log)
-      // We capture stdout entirely, then restore after runtime.start().
-      bootQuiet = true;
-      process.stdout.write = (chunk: any, ...rest: any[]) => {
-        if (bootQuiet) return true;  // swallow
-        return (origStdoutWrite as any)(chunk, ...rest);
-      };
-      console.log = (...args: any[]) => { if (!bootQuiet) originalConsoleLog(...args); };
-      console.debug = (...args: any[]) => { if (!bootQuiet) originalConsoleDebug(...args); };
+      // We intercept stdout entirely, then restore after runtime.start().
+      //
+      // Intercepted is not discarded (#4012): `ObjectLogger` routes `warn` to
+      // stdout — only `error`/`fatal` go to stderr — so dropping these bytes
+      // dropped every boot-phase warning a plugin logged, on both `os serve`
+      // and `os dev` (which inherits this child's stdio), at every log level.
+      // The chatter still never reaches the banner; the kernel-logger records
+      // among it are buffered and replayed once the banner has printed.
+      bootQuiet = !verboseBoot;
+      if (!verboseBoot) {
+        process.stdout.write = (chunk: any, ...rest: any[]) => {
+          if (bootQuiet) {
+            bootLogs.write(chunk, typeof rest[0] === 'string' ? rest[0] : undefined);
+            // Honor the write callback so a caller awaiting drain still resumes.
+            const cb = rest.find((a) => typeof a === 'function');
+            if (cb) cb();
+            return true;
+          }
+          return (origStdoutWrite as any)(chunk, ...rest);
+        };
+        console.log = (...args: any[]) => { if (!bootQuiet) originalConsoleLog(...args); };
+        console.debug = (...args: any[]) => { if (!bootQuiet) originalConsoleDebug(...args); };
+      }
 
       // Load configuration
       // --prebuilt: load as native ESM (no esbuild, no bundle-require) —
@@ -784,18 +825,13 @@ export default class Serve extends Command {
       // Import ObjectStack runtime
       const { Runtime } = await import('@objectstack/runtime');
 
-      // Resolve the kernel logger level. Honors --verbose / --log-level and
+      // The kernel logger level. Honors --verbose / --log-level and
       // $OS_LOG_LEVEL / $LOG_LEVEL, defaulting to `warn` so flow/hook
       // execution failures surface even when the CLI manages its own output
       // (ADR-0032 "fail loudly"; see #1533). `--log-level silent` restores the
-      // old fully-quiet behavior.
-      const loggerConfig = {
-        level: resolveLogLevel({
-          verbose: flags.verbose,
-          flag: flags['log-level'],
-          envLevel: readLogLevelEnv(),
-        }),
-      };
+      // fully-quiet behavior. Resolved above the boot-quiet window, which
+      // keys off it too (#4012).
+      const loggerConfig = { level: bootLogLevel };
 
       // Cluster wiring: env-driven driver selection (mirrors OS_DATABASE_URL).
       // The remote driver self-registers on import; import it dynamically so it
@@ -2391,6 +2427,11 @@ export default class Serve extends Command {
       // never accept a request — shutdown immediately so the deploy
       // pipeline can move on.
       if (process.env.OS_MIGRATE_AND_EXIT === '1') {
+        // This path exits before the banner, so it has to replay the boot
+        // diagnostics itself — a deploy pipeline is precisely where a
+        // degraded-boot warning must not vanish (#4012).
+        const migrateDiagnostics = collectBootDiagnostics();
+        if (migrateDiagnostics) printBootDiagnostics(migrateDiagnostics);
         console.log(chalk.green(`✓ Migration complete (${loadedPlugins.length} plugins started against ${resolvedDatabaseUrl ? redactConnectionUrl(resolvedDatabaseUrl) : 'configured DB'})`));
         try {
           await kernel.shutdown();
@@ -2469,6 +2510,11 @@ export default class Serve extends Command {
         seededAdmin,
         automation: automationSummary,
         seeds: seedSummary,
+        // #4012 — every boot-phase `logger.warn` the quiet window intercepted,
+        // replayed here. Without this the window is a drain: the ADR-0110 D5
+        // `[action-governance]` inventory, degraded-boot notices and flow
+        // binding failures all reached stdout and none reached a terminal.
+        bootDiagnostics: collectBootDiagnostics(),
         // #3167 — surface the default-on MCP endpoint in the dev loop, where an
         // AI client can connect to operate the running app. Same decision point
         // that auto-loads the plugin + gates the route, so the banner never
@@ -2512,6 +2558,10 @@ export default class Serve extends Command {
       restoreOutput();
       console.log('');
       printError(error.message || String(error));
+      // A boot that died is when its warnings matter most, and the banner that
+      // would normally carry them never printed (#4012).
+      const diagnostics = collectBootDiagnostics();
+      if (diagnostics) printBootDiagnostics(diagnostics);
       if (process.env.DEBUG) console.error(chalk.dim(error.stack));
       this.exit(1);
     }