fix(cli,core): the ready line reports the degraded boot the kernel already concluded

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_015QE8qk46e5CHJxyQEUjbf8

Author: os-project-manager

.changeset/ready-signal-reports-degraded-boot.md

@@ -0,0 +1,12 @@
+---
+"@objectstack/core": patch
+"@objectstack/cli": patch
+---
+
+The `Server is ready` line now reports the degraded boot it is standing on, instead of printing a green `✓` over it.
+
+`✓ Server is ready` and the kernel's `System started with degraded capabilities. Missing core services: …` were two statements about one boot, produced by two packages — the banner in `@objectstack/cli`, the conclusion in `@objectstack/core` — with **no data path between them**. So the ready signal did not depend on the thing that broke, and therefore could not report it. Measured twice within a day, from unrelated causes: an objectui CI boot where the auth plugin failed and not one `sys_*` table existed, and this repo's own weekly registry canary on the published `npx create-objectstack@latest` on-ramp, where the tick printed directly **above** four boot warnings. In the second case the ready line carried no weight in the job's verdict at all — it was present, green, wrong, and believed by nobody.
+
+- **The data path.** `ObjectKernel.validateSystemRequirements()` now publishes the list it had already computed — the same array behind its own warning — on the kernel's service registry, which is the seam boot facts already cross to reach the banner (`serve` reads `auth` and `seed-summary` off it the same way). No member and no type is added to `@objectstack/core`'s public surface, and nothing re-derives which services count as `core`: that judgement stays in `ServiceRequirementDef` alone.
+- **The line.** On a degraded boot the banner prints `⚠ Server is ready — DEGRADED: missing core services: <names>`, naming exactly what the kernel found missing. On a healthy boot the ready block is byte-for-byte unchanged, so an ordinary boot's output does not move.
+- **Readiness is NOT made strict.** Nothing about what boots, binds, or exits changes. A machine deliberately running without auth still starts, still prints ready, and still exits 0 — the line just says what state it is ready in.

packages/cli/test/serve-ready-degraded-boot.e2e.test.ts

@@ -1,10 +1,20 @@
 // Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
 
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
+import { spawn, type ChildProcessByStdio } from 'node:child_process';
 import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { randomPort, runServe } from './helpers/serve-process.js';
+import { join, resolve } from 'node:path';
+import type { Readable } from 'node:stream';
+import { fileURLToPath } from 'node:url';
+import {
+  childEnv,
+  E2E_SECRET_KEY,
+  portContentionError,
+  requireBuiltCli,
+  reservePort,
+  RUN_JS_RESOLVES_FROM_DIST,
+} from './helpers/serve-process.js';
 
 /**
  * #16630 — a REAL `os serve` boot, degraded, read end to end.
@@ -26,106 +36,180 @@ import { randomPort, runServe } from './helpers/serve-process.js';
  * ⇒ Testing one package's output is the perspective that produced the defect.
  * `src/utils/format.server-ready-degraded-boot.test.ts` closes the seam over a
  * real `ObjectKernel`; this file closes it over the real COMMAND — the whole
- * assembly of plugins, tiers and banner that a user actually runs.
+ * assembly of plugins, tiers and banner a user actually runs.
  *
- * ## How the degradation is provoked — the shape both incidents had
+ * ## Why `bin/run.js` with `NODE_ENV` unset, and not `runServe()`
  *
- * Not a fault injected into the kernel: `serve` auto-registers `AuthPlugin`
- * only when a secret is resolvable, and outside `--dev` there is no fallback
- * one — so a production boot with no `OS_AUTH_SECRET` skips auth by its own
- * documented rule, and `auth` (a `core` service with no in-memory fallback)
- * is genuinely absent. That is the same end state both incidents reached by
- * other routes: a plugin that did not load and a core service that is not
- * there.
+ * The degradation has to be REACHED, not injected, and the only reachable
+ * spelling is production posture. `serve` auto-registers `AuthPlugin` when a
+ * secret resolves; outside `--dev` there is no fallback secret, so a production
+ * boot with no `OS_AUTH_SECRET` skips auth by the command's own documented rule
+ * (`⚠ AuthPlugin skipped — set OS_AUTH_SECRET …`) and `auth` — a `core` service
+ * with no in-memory fallback — is genuinely absent. That is the end state both
+ * incidents reached by other routes: a plugin that did not load, and a core
+ * service that is not there.
  *
- * ⚠️ This is also the NEGATIVE CONTROL for the acceptance rule that start and
- * exit behaviour must not change: that boot is a machine DELIBERATELY running
- * without auth, and it must still reach the banner and still be a live server.
- * Readiness is not made strict here; the ready line only says what state it is
- * ready in.
+ * ⛔ `runServe()` cannot reach it. That helper spawns `bin/run-dev.js`, which
+ * sets `NODE_ENV = 'development'` before argv is parsed, so `isDev` is true,
+ * the dev fallback secret applies, auth ALWAYS loads and the boot is never
+ * degraded. Measured: switching this file to `runServe()` makes both legs
+ * healthy and the degraded assertions unreachable — a green that measures
+ * nothing. `bin/run.js` with `NODE_ENV` genuinely unset is the only shape that
+ * reaches the gate, which is also why {@link requireBuiltCli} guards the file.
+ *
+ * ⚠️ The degraded leg is ALSO the negative control for the acceptance rule that
+ * start and exit behaviour must not change: it is a machine deliberately
+ * running without auth, and it still reaches the complete banner and is still a
+ * live server afterwards. Readiness is not made strict here; the ready line
+ * only says what state it is ready in.
  */
 
+/** The complete banner — keyed on its LAST line, so the whole block is on the stream. */
+const READY_BANNER_TAIL = /Press Ctrl\+C to stop/;
+
+const HERE = resolve(fileURLToPath(import.meta.url), '..');
+/** `bin/run.js` — the SHIPPED entrypoint. See the header for why this one. */
+const CLI = resolve(HERE, '../bin/run.js');
+
 const BARE_CONFIG = 'export default {};\n';
 
-let degradedDir: string;
-let healthyDir: string;
+/** What `spawn(…, { stdio: ['ignore', 'pipe', 'pipe'] })` returns — no `stdin`. */
+type BootChild = ChildProcessByStdio<null, Readable, Readable>;
 
-beforeAll(() => {
-  degradedDir = mkdtempSync(join(tmpdir(), 'os-ready-degraded-'));
-  writeFileSync(join(degradedDir, 'objectstack.config.ts'), BARE_CONFIG, 'utf8');
+const children: BootChild[] = [];
+let fixtureDir: string;
+
+interface Boot {
+  out: string;
+  err: string;
+  child: BootChild;
+}
+
+/**
+ * Spawn `os serve` in production posture and resolve once the COMPLETE banner
+ * is on the stream. Extra `env` entries override the base; `undefined` unsets.
+ */
+async function boot(env: Record<string, string | undefined> = {}): Promise<Boot> {
+  const port = reservePort();
+  const child = spawn(process.execPath, [CLI, 'serve', 'objectstack.config.ts', '--port', String(port)], {
+    cwd: fixtureDir,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    // `childEnv`, never a bare `...process.env` — see its header (#11267).
+    env: childEnv({
+      NO_COLOR: '1',
+      OS_DATABASE_URL: ':memory:',
+      OS_LOG_LEVEL: '',
+      OS_DISABLE_CONSOLE: '1',
+      // Production posture refuses to mint a crypto key; supplying a stable one
+      // keeps the refusal out of the way of the property under test.
+      OS_SECRET_KEY: E2E_SECRET_KEY,
+      // ⭐ Truly unset — the value that leaves the boot in production posture
+      // (and leaves oclif resolving the command from `dist/`). Node omits an
+      // `undefined` entry rather than inheriting the vitest worker's own.
+      NODE_ENV: undefined,
+      ...env,
+    }),
+  }) as BootChild;
+  children.push(child);
 
-  healthyDir = mkdtempSync(join(tmpdir(), 'os-ready-healthy-'));
-  writeFileSync(join(healthyDir, 'objectstack.config.ts'), BARE_CONFIG, 'utf8');
+  let out = '';
+  let err = '';
+
+  await new Promise<void>((ready, fail) => {
+    const timer = setTimeout(() => {
+      fail(new Error(
+        'serve never printed its COMPLETE ready banner (last line: "Press Ctrl+C to stop")'
+        + `\n--- stdout ---\n${out}\n--- stderr ---\n${err}`,
+      ));
+    }, 150_000);
+    const onData = () => {
+      if (READY_BANNER_TAIL.test(out + err)) {
+        clearTimeout(timer);
+        ready();
+      }
+    };
+    child.stdout.on('data', (d) => { out += String(d); onData(); });
+    child.stderr.on('data', (d) => { err += String(d); onData(); });
+    child.on('exit', (code) => {
+      clearTimeout(timer);
+      // A lost port race gets its own failure before the generic one (#12441):
+      // `serve exited 1 before the banner` is what it produces otherwise, and
+      // that reads as a verdict about this file's subject when it is not.
+      fail(
+        portContentionError(out + err, 'os serve (bin/run.js, NODE_ENV unset ⇒ production)', port)
+        ?? new Error(`serve exited ${code} before the ready banner\n--- stdout ---\n${out}\n--- stderr ---\n${err}`),
+      );
+    });
+  });
+
+  return { out, err, child };
+}
+
+beforeAll(() => {
+  requireBuiltCli(RUN_JS_RESOLVES_FROM_DIST);
+  fixtureDir = mkdtempSync(join(tmpdir(), 'os-ready-degraded-'));
+  writeFileSync(join(fixtureDir, 'objectstack.config.ts'), BARE_CONFIG, 'utf8');
 });
 
 afterAll(() => {
-  for (const dir of [degradedDir, healthyDir]) {
-    if (dir) rmSync(dir, { recursive: true, force: true });
+  for (const child of children) {
+    try { child.kill('SIGTERM'); } catch { /* already gone */ }
   }
+  if (fixtureDir) rmSync(fixtureDir, { recursive: true, force: true });
 });
 
 describe('os serve — the ready line reports a degraded boot (#16630)', () => {
   it(
     'prints ready AND the missing core service in the same output, with no unconditional tick',
     async () => {
-      const { stdout, stderr } = await runServe(degradedDir, ['--port', randomPort()], {
-        waitFor: /Press Ctrl\+C to stop/,
-        timeoutMs: 240_000,
-      });
-      const seen = `\n--- stdout ---\n${stdout}\n--- stderr ---\n${stderr}`;
-      const output = stdout + stderr;
+      const { out, err, child } = await boot();
+      const seen = `\n--- stdout ---\n${out}\n--- stderr ---\n${err}`;
+      const output = out + err;
 
       // The premise: this boot really is degraded, and the kernel really said
-      // so. Asserted first — without it every assertion below is vacuous.
+      // so. Asserted FIRST — without it every assertion below is vacuous.
       expect(output, `this boot was not degraded${seen}`).toContain(
         'System started with degraded capabilities. Missing core services: auth',
       );
 
       // ⭐ BOTH sides, in ONE output — the property the two packages could not
       // hold between them before the data path existed.
-      expect(stderr, `serve never reported ready${seen}`).toContain('Server is ready');
-      expect(stderr, `the ready line withheld the degradation${seen}`).toContain(
+      expect(err, `serve never reported ready${seen}`).toContain('Server is ready');
+      expect(err, `the ready line withheld the degradation${seen}`).toContain(
         '⚠ Server is ready — DEGRADED: missing core services: auth',
       );
 
       // ⭐ The defect itself, gone: the green tick may not appear on a boot the
       // kernel has recorded as degraded.
-      expect(stderr, `the unconditional green tick survived${seen}`).not.toContain(
-        '✓ Server is ready',
-      );
+      expect(err, `the unconditional green tick survived${seen}`).not.toContain('✓ Server is ready');
 
-      // ⛔ Start behaviour unchanged: a machine deliberately without auth still
-      // boots all the way through the banner. `runServe` only resolves once
-      // the banner's LAST line is on the stream, so reaching here IS that.
-      expect(stderr, `boot stopped short of the banner tail${seen}`).toContain(
-        'Press Ctrl+C to stop',
-      );
+      // ⛔ Start behaviour unchanged. Reaching here already means the COMPLETE
+      // banner printed; the process being alive is the other half.
       expect(output).not.toContain('rollback complete');
+      expect(child.exitCode, `serve exited during a boot it called ready${seen}`).toBeNull();
     },
     240_000,
   );
 
   it(
     'leaves a healthy boot printing exactly the tick it always printed',
     async () => {
-      // Same fixture, same command — the ONLY difference is that auth can now
-      // register, so nothing is missing. An "always append a status line"
-      // implementation passes the degraded case above and fails here.
-      const { stdout, stderr } = await runServe(healthyDir, ['--port', randomPort()], {
-        waitFor: /Press Ctrl\+C to stop/,
-        timeoutMs: 240_000,
-        env: { OS_AUTH_SECRET: 'os-16630-healthy-leg-secret-not-a-real-credential' },
+      // Same fixture, same entrypoint, same posture — the ONLY difference is
+      // that auth can now register, so nothing is missing. An "always append a
+      // status line" implementation passes the degraded leg and fails here.
+      const { out, err } = await boot({
+        OS_AUTH_SECRET: 'os-16630-healthy-leg-secret-not-a-real-credential',
       });
-      const seen = `\n--- stdout ---\n${stdout}\n--- stderr ---\n${stderr}`;
-      const output = stdout + stderr;
+      const seen = `\n--- stdout ---\n${out}\n--- stderr ---\n${err}`;
+      const output = out + err;
 
       // The premise for THIS leg: nothing was missing.
       expect(output, `the healthy leg booted degraded${seen}`).not.toContain(
         'System started with degraded capabilities',
       );
 
-      expect(stderr, `healthy boot lost its ready tick${seen}`).toContain('✓ Server is ready');
-      expect(stderr, `healthy boot grew a degraded notice${seen}`).not.toContain('DEGRADED');
+      expect(err, `healthy boot lost its ready tick${seen}`).toContain('✓ Server is ready');
+      expect(err, `healthy boot grew a degraded notice${seen}`).not.toContain('DEGRADED');
     },
     240_000,
   );