`os migrate recorded-by --json` 的 stdout 里混着内核 INFO 日志，payload 无法直接 JSON.parse

[qq9340100]

发现自 #4873 的实现过程(修那条 issue 时必须绕开本问题才能断言 payload)。未认领。 与 #4873 是不同的 bug —— #4873 修的是退出码,修好之后本条照旧复现。

现象

--json 是给程序消费的,但 os migrate recorded-by --json 的 stdout 上除了 JSON payload,还夹着内核启动的 INFO 日志,所以整个 stdout 不是一份合法 JSON:

os migrate recorded-by --json 2>/dev/null | jq .
# parse error: Invalid numeric literal at line 1, column 13

实测(丢弃 stderr 后把 stdout 整份喂给 JSON.parse):

JSON.parse FAILED: Unexpected token 'S', "[Standalone"... is not valid JSON

stdout 的实际形状是这样(payload 上下都有日志):

[StandaloneStack] no compiled artifact at '…' — booting without one (run 'os compile' to build it)
2026-08-07T10:09:22.887Z INFO Registered metadata loader: filesystem (file:)
…约 60 行 INFO…
2026-08-07T10:09:23.387Z INFO ✅ Bootstrap complete
{
  "planId": "metadata.recorded-by-sentinel-to-null",
  "sentinel": "system",
  "pending": 0,
  "applied": false,
  "duration": 504
}
2026-08-07T10:09:23.388Z INFO Graceful shutdown started
2026-08-07T10:09:23.394Z INFO ✅ Graceful shutdown complete

注意 stderr 是空的 —— 日志没走 stderr,是实打实占了 stdout。

归因(已定位到行,未修)

packages/core/src/logger.ts:343:

const stream = proc ? (isErrorLevel ? proc.stderr : proc.stdout) : undefined;

即 error/fatal 走 stderr,info/debug/warn 走 stdout。凡是 --json 且要 boot 内核的子命令都会被这一条命中,不止 migrate recorded-by:bootSchemaStack 系(migrate plan / apply / resume / summary-nulls / value-shapes / files-to-references / meta resync)都在同一条路径上。不 boot 内核的命令(如 os migrate meta)不受影响 —— packages/cli/test/migrate-meta.e2e.test.ts 至今可以直接 JSON.parse(stdout),这也是为什么这个问题一直没被 e2e 测出来。

为什么值得修

--json 这个 flag 的唯一受众是程序。一个必须先靠启发式把日志行剔掉才能解析的 --json,等于没有 --json:消费者要么写一段"找最后一个独占一行的 { 到配对 }"的提取器(#4873 的 e2e pin 里就被迫写了一份,packages/cli/test/migrate-exit-code.e2e.test.ts 的 jsonPayload()),要么就解析失败。而这类启发式在 payload 恰好紧邻某行日志、或日志里出现形似 JSON 的内容时会静默取错。

与 #4873 是同一受众的同一类伤害(成功的命令,程序侧却拿不到可用结果),但落点完全不同,所以单开一条。

可能的修法(未决,留给分诊)

1. --json 时把内核 logger 的输出重定向到 stderr(payload 独占 stdout);
2. --json 时把日志级别压到 error(信息量损失更大,且 warn 仍会丢);
3. logger 默认全部走 stderr,stdout 只留给命令的正式输出(POSIX 惯例,影响面最大)。

三者对 os serve / os dev 的日志观感影响不同,建议由维护者定方向后再动手 —— 本条只负责把事实和落点记清楚。

复现

cd examples/app-crm
rm -f /tmp/t.db*
OS_DATABASE_URL="file:/tmp/t.db" node ../../packages/cli/bin/run.js migrate recorded-by --json 2>/dev/null | jq .

Refs #4873。

[claude]

Triage: pm:queue + domain:cli + target:v17.

Stale-premise check — origin/main 72847c5

packages/core/src/logger.ts still routes by level, verbatim as filed:

const isErrorLevel = level === 'error' || level === 'fatal';
const proc = typeof process !== 'undefined' ? (process as any) : undefined;
const stream = proc ? (isErrorLevel ? proc.stderr : proc.stdout) : undefined;

So info on stdout is unchanged, and every --json subcommand that boots the kernel (the bootSchemaStack family: migrate plan / apply / resume / recorded-by / summary-nulls / value-shapes / files-to-references, plus meta resync) is on that path. #4873 is closed completed, which confirms the body's claim that this survives it: that issue fixed the exit code, not the stream.

Domain anchoring — cli, with a named condition that would move it

Routed by landing site under the in-scope route, not by where the root-cause line sits. The narrow fix is to stop the kernel's boot logs from landing on --json stdout at the seven-or-so command entry points, i.e. packages/cli ⇒ domain:cli. There is already an in-repo idiom for exactly this: packages/cli/src/commands/plugin/build.ts:180 and packages/cli/src/utils/build-runtime.ts:143 both boot with logLevel: 'silent' for the same reason.

⛔ Route 3 in the body (make the logger default to stderr repo-wide) is out of this issue's scope and is not being queued here. It changes os serve / os dev output for every existing user and every log-scraping deployment, which is a maintainer call, and it would land in packages/core ⇒ domain:engine-core, a different seat. If whoever takes this concludes route 3 is the only honest fix, that is a needs_decision return, not a silent widening.

PM mechanism assumption (verify, and falsifying it is welcome): that the --json paths can be quieted or redirected at the CLI layer without a packages/core change. logLevel: 'silent' (route 2) demonstrably can be set from the CLI today; a stderr redirect (route 1, which preserves the diagnostics) may need a destination knob that logger.ts does not currently expose. If it does, say so and price route 1 vs route 2 in the report rather than assuming this note settled it.

Acceptance the queue entry carries

--json stdout must be exactly one JSON document — JSON.parse(stdout) succeeds with no heuristic extraction. The repro in the body is scriptable as-is, and packages/cli/test/migrate-exit-code.e2e.test.ts's jsonPayload() helper (written under duress by #4873) is the pin that should become unnecessary.

Release board

target:v17 under criterion ② (a declared surface that lies) and ④ (copy-the-docs-and-it-fails). --json's only audience is a program; a --json whose output is not parseable is a documented flag that does not do what it says. Its sibling #4873 carried target:v17 for the same audience and the same class of harm.

Dedup (three repos, open issues and PRs)

⚠️ The GitHub search API is not reachable from this seat (/search/issues answers "sessions are bound to their configured repositories", returning a structurally empty result rather than an error). Dedup was done by paginating all 442 open issues and PRs across the three repos and matching full text locally, on --json+stdout, proc.stdout, JSON.parse(stdout), and logger.ts.

No shadow — the only match was the domain:cli seat post. #4873 is closed and is the sibling, not a duplicate: same audience, different landing site, and it is explicitly still reproducible after that fix.

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[os-project-manager]

Claim: PM loop round 2 (domain:cli seat, 2026-08-08 shift)
Session: session_017uFVNMmTxLpmfQYiuKM1Yx
Branch: claude/issue-6217-json-stdout-purity
Worktree: objectstack-issue-6217
Domain: domain:cli
File surface: packages/cli/src/** (the bootSchemaStack --json command entry points) + its e2e tests + one .changeset/*.md. ⛔ EXPLICITLY EXCLUDED: packages/core/src/logger.ts — route 3 (repo-wide stderr default) is out of scope per triage, and a change there is domain:engine-core, a different seat. If the honest fix requires a packages/core change, that is a needs_decision return, not a silent widening. (Stop on breach; explain in the report.)
Serial constraints cleared: no dev in flight in this lane. PR #6481 (issue #6266) is already ACCEPTed and sitting in the merge queue; it touches packages/cli but only src/utils/format.exit-code.test.ts, which is disjoint from the command entry points here — and it is queued rather than being authored, so there is no concurrent-edit race. Container sizing: M, mode:subagent shared container.

---

Generated by Claude Code