feat(turns): watch persisted journal progress

[mikamikasuki]

Goal and delivered outcome

• Outcome basis: issue #5886 identifies a gap in operator visibility during long-running Turns and suggests journal polling as a workaround.
• Goal and gap: On canonical main 647e216bacc0a69368dccc18fcb52dcba6002553, turn inspect-journal reads once, so operators cannot follow persisted phase checkpoints while a run is active.
• Observable change: The CLI now supports opt-in --watch polling with JSON Lines or Markdown output. It emits only changed, allowlisted status and completed-phase fields and exits at a terminal journal state. It rejects inconsistent typed journal results before emitting progress, while still allowing a consistent in_progress journal to be observed.
• Scope: Read-only CLI output and English/Chinese custom-runner guidance. This does not report transient, unpersisted host progress or change execution, authority, quota, or settlement behavior.

Author declaration

• Written by: model_agent — OpenAI GPT-6 Luna Medium.
• Some coding work was AI-assisted. I personally reviewed the changes, verified the relevant behavior and tests, and take responsibility for the submission.

Implemented against

• Specification: issue Long-running goals: zero mid-run progress events (milestone RFC not landed); operator blind for the entire run #5886 and the existing typed Turn journal inspection contract.

Criterion	Result	Evidence
Follow persisted status and phase checkpoints	Implemented	turn inspect-journal --watch; concurrent-writer regression
Keep progress output allowlisted and consistent	Implemented	Existing typed inspection result gates each event; mismatched owner and invalid phase regressions
Document the opt-in command for custom runners	Implemented	English and Chinese integration guides; CLI help

Validation

• Tested head: d1e47f26f8cf630171d45771b2184e1a5601a384, based on canonical main 647e216bacc0a69368dccc18fcb52dcba6002553.
• Regression/unit: tests/test_loopx_turn_journal_inspection.py and tests/test_loopx_turn_executor.py — 115 passed on this exact head, including inconsistent owner/phase rejection and consistent in-progress observation.
• Static: Ruff on changed Python modules and tests, Python compilation, and git diff --check origin/main...HEAD passed. Both commits contain DCO Signed-off-by trailers.
• Earlier full validation on pre-rebase implementation head a7f4b1f: strict mypy (19 source files), TypeScript typecheck, semantic smoke, CLI help, and pre-merge canary (14/14) passed.
• Hosted checks after this rebase have started: Summary is in progress; DCO, dependency review, Frontstage Pages, Release Artifacts, and both adapter-contract checks are queued; merge-gate is expected. The changes-requested review refers to older head f4d9015; the fix and current-head test results are documented in the review follow-up. No merge is claimed.

Coverage and boundary

Tests cover changed-only event emission, terminal exit, interval validation, private-content exclusion, inconsistent owner/phase rejection, and observation of persisted checkpoints from a concurrent journal writer. The journal must exist when watching starts. Transient host progress that has not been persisted is outside this change.

Frontend / visual evidence

• UI impact: none; this adds a CLI option and integration documentation.

Type of change

• New feature
• Documentation update
• Test update

LoopX area

• Control plane

Technical direction

Additive operator-facing observability for the existing Turn journal. No architecture or authority contract changes.

Shared-authority RFC fixture impact

• Production-scale fixture schema: N/A.
• Semantic dimensions: unchanged; no shared-authority schema or provider semantics changed.
• Provider conformance arms: N/A.
• Read-only backend rehearsal: N/A.

Boundary checklist

• No private state, credentials, raw traces, internal links, or local paths are included.
• No maintainer-owned work is duplicated.
• The change is scoped to issue Long-running goals: zero mid-run progress events (milestone RFC not landed); operator blind for the entire run #5886.
• Every commit includes a DCO Signed-off-by trailer.

See validation disclosure guidance.

[loopx-agent]

Reviewer: model_agent; model=gpt-6.1-sol; provider=OpenAI; runtime_reported; reasoning_effort=xhigh.

Reviewed exact head f4d90159e370c8c8ab3cad01778395c49b529cdc against base 3ed5d6bc88ffaaa05f2b1bc6a98ed5d921379fd1. REQUEST_CHANGES：一项当前进度投影缺陷。

动机

运行长任务的自定义 runner 操作者需要及时看到已经写入 journal 的阶段进展。
旧命令只能单次查看；新 watch 能随持久化阶段变化输出，但身份不匹配或 journal 不一致时仍输出成功事件。
真实 CLI 已观察到并发写入的阶段变化；同时复现了错误身份和非法阶段被当成正常 committed 进度。
本 PR 不提供未持久化的 Host 步骤进度，不改变执行权限、额度或停止结算，也未交付 packaged frontend。
当前 safe 进度流仍缺一致性拒绝；长时间 Host 阶段的细粒度进度和 frontend 采用仍未验收。

完整读取 #5886 后，我将 journal 轮询视为它明确提出的有用 workaround，而不是完整解决 40–85 分钟 Host 步骤可见性的声明。召回的恢复旅程建议只用于检查这个交付边界，不继承旧结论或宣称记忆提升了模型效果。

改动思路

轮询和格式化适合留在既有 CLI I/O adapter；一致性必须继续由现有 TypeScript owner 决定。
本轮最小修复是在构造事件前消费 journal_consistent，安全报告绑定或阶段错误；保留正常 in_progress 观察。

与手工反复调用单次 inspection 相比，changed-only 流能减少操作成本；无需另造 journal、事件持久化或执行框架。最强反对理由是：读到了文件不代表 journal 一致，缩短投影不能丢掉错误语义。当前代码复用低层读取，却没有消费它已提供的一致性结论。

具体改动

全量 B..H 覆盖六个文件、+340/-0：两份 runner 指南加入可选调用及终止说明，registration 加入 --watch / --watch-interval，inspection 增加轮询和状态/阶段 tuple 去重，rendering 增加 Markdown 进度格式，原 inspection 测试文件加入 mock 快照、非法间隔和并发 writer 三个用例。

关键代码讲解

• register_turn_commands 保持 watch 默认 false；只有显式调用才进入新分支，help/指南是可选入口说明。
• handle_turn_journal_inspection 继续使用实际锁定 journal 和 TypeScript 解释器，再以 (status, completed_phases) 去重；ok 只证明读取成功，不能替代 journal_consistent。
• render_loopx_turn_journal_progress_markdown 格式化新投影，不能修正前面已经丢掉的绑定或阶段验证。

规格依据：https://github.com/loopx-project/loopx/issues/5886，issue body revision sha256:b6a0badb06b9a51843d6ad42f4d07f3162d7e553a799ee21d723920e2f71c647；同时对照 3ed5d6bc88ffaaa05f2b1bc6a98ed5d921379fd1 的 loopx/control_plane/turn_driver/turn_journal.ts 和原 inspection 契约。persisted-progress implemented：真实 CLI 观察到三个持久化快照；truthful-safe-projection not_met：下面的反例；transient-host-progress deferred：仍在 #5886 原有需求中，未交付 frontend 或未持久化 Host 事件。

语义与CI对齐

新 loopx_turn_progress_event_v0 是观察投影，不是执行回执。terminal 的本地轮询集合复用已有状态语义；身份和 ordered-prefix 的权威仍在 TS owner。开发期 advisory 和 full semantic smoke 均通过，但 advisory 的空结果不覆盖动态语义，也不能证明这个有损投影正确。未查询、轮询或等待 CI。

对主干的风险

[P2] 不要把读取成功当成一致的进度。 用同一真实 committed journal，把 CLI agent 改成不同身份：原 inspection 报 owner_matches=false、journal_consistent=false、owner_mismatch 和 blocked recovery；watch 却把调用者填写的 agent_id 放进 committed 事件并 exit 0。将 completed_phases 改成非法合成文本，原 typed reader 同样明确报告不一致；watch 原样输出文本并成功退出。所有作者的 112 项相关测试仍通过。这里证明的是新增投影丢失诊断和错误归属；没有声称本地可信 CLI 成了远程认证边界或实际泄露了私人账户数据。

最小修复：消费现有 journal_consistent，在绑定或阶段不一致时返回安全可读的诊断，不生成可信进度事件；合法 in_progress 虽然 replay_blocked，仍应可观察，因此不要直接把 replay_legal 当 watcher 准入。补 real CLI 的错 owner、非法 prefix 和合法 in_progress 负/正例。

独立 source-checkout 验证：112 focused tests、Ruff、configured mypy 19、TS typecheck、完整 semantic smoke、DCO 和 diff check 通过。另起真实 CLI 与锁定文件 writer，依次观察 in_progress 空阶段、host_execute、committed；JSONL/Markdown terminal 和 0/NaN/Inf/负 interval 边界已验。关闭 watch 时，B/H 的完整 inspection JSON 逐字段相等，无归一化；base 的 --watch exit 2。观察过程未改 journal 内容，也未执行 Host、额度或 settlement effects。

两次私有 probe 准备失败（重复建目录、误用缺少入口的 Python module）已保留并修正，没有把它们记为 PR 回归。以上结论来自修正后真实 CLI 和实际 TS 读取，未用 mock 提供所需后置条件。未测试长时间轮询成本、live 模型、Windows、packaged frontend 或安装采用。

我的整体评价

REQUEST_CHANGES。真实 persisted-progress 入口有价值，默认单次路径保持，但错误 journal 不能被包装成健康进度。未来重构检查落在同一小边界：保留 CLI I/O，将一致性判断留给现有 TS owner，补齐投影而不是添加第二套状态规则。该修复与正/负 CLI 回读通过后，再评估这个有界增量；不要求本 PR 一次完成整个 milestone 或 frontend 产品。

English verdict: REQUEST_CHANGES — exact head f4d9015; the new watch stream drops existing typed identity/consistency diagnostics and reports invalid journals as successful committed progress. 112 focused tests, static/semantic checks and healthy real concurrent CLI observation pass; independent wrong-owner and invalid-phase probes expose the missing guard.

[mikamikasuki]

Review follow-up for the findings on f4d9015:

The watch path now requires the existing typed inspection result to report journal_consistent=true before it emits a progress event. An inconsistent journal prints the existing structured inspection diagnostic and exits 1. The gate does not require replay_legal, so a consistent in_progress journal remains observable.

Added real CLI regressions for mismatched owner and invalid phase prefix, plus an in_progress-to-committed watch. Before the fix, both negative cases returned 0 and emitted the progress projection. On commit a7f4b1f, all three focused regressions and the existing watch/concurrent-writer cases pass; the full inspection/executor modules pass 115 tests. Ruff, Python compilation, strict mypy (19 source files), CLI help, diff checks, and the repository premerge canary (14/14) pass.

The commit is pushed to this PR branch. Fresh hosted checks are queued; I will report their results when they finish.

[mikamikasuki]

CI attribution for run 37862599353 at PR head a7f4b1f: the Frontstage Pages build fails in examples/blog-bilingual-index-smoke.mjs because it expects one exact relative href for edgebench-feedback-and-memory. I reproduced the same failure on this PR's exact base 3ed5d6b (node examples/blog-bilingual-index-smoke.mjs, exit 1); the changed files in #5998 do not touch the smoke or blog content. The equivalent-destination correction is already submitted in PR #5968, whose head passes all six bilingual article pairs locally. This is a pre-existing unrelated check failure, not a regression from #5998. #5998's other hosted checks are still pending; I am not claiming the overall run is green.

[mikamikasuki]

CI attribution for run 37862599634 at head a7f4b1f: test-shard (1) completed with 4 failures, 4,757 passed, and 71 skipped; test-shards (2)–(4) and dashboard-acceptance were cancelled. The admission-codec replay assertion reproduces 3/3 on current upstream main 0e5acf and on this PR head, so it is not caused by this diff; the assertion predates this PR and now conflicts with the exact-source recovery boundary added in #5939. The canonical-successor failure is also present on current main: the parser supplies derived content_revision metadata to a strict domain fixture. Its correction is already in #5994. Two scripted Doubao actor cases raised provider_transport_failed, but the job output suppresses the underlying exception, so I cannot attribute those further. Other hosted checks passed or are listed separately above.

[mikamikasuki]

Current-head attribution for Frontstage Pages job 113662411500 (run 37881637281, head 6da959d): it fails on the same edgebench-feedback-and-memory paired-link assertion. I ran node examples/blog-bilingual-index-smoke.mjs three times on exact PR base fac40bb and three times on current head; all six runs exit 1 with the same assertion. #5998 changes only journal CLI, docs, and tests, not this smoke or the blog catalog. The pending smoke correction is in open PR #5968, whose diff changes this validation script. This is a baseline failure, not a #5998 regression. Other checks remain pending; I have not treated the overall run as green.

[mikamikasuki]

Rebased the existing #5998 branch onto canonical main. Current head d1e47f2; base 647e216. The journal_consistent guard and wrong-owner/invalid-phase CLI regressions are retained. On this exact head, tests/test_loopx_turn_journal_inspection.py plus tests/test_loopx_turn_executor.py pass (115); Ruff, Python compilation, diff check, and both DCO trailers pass. Fresh hosted Summary, DCO, dependency, two adapter-contract, and two build checks have started and are pending. The REQUEST_CHANGES review is on prior head f4d9015; the fix was already documented and review remains requested; please reassess this rebased head.