@surlymochan/evalid 0.5.19 → 0.5.21

package/CHANGELOG.md

@@ -3,6 +3,27 @@
 All notable changes to this project are documented here. Detailed notes live in
 [RELEASE_NOTES.md](RELEASE_NOTES.md).
 
+## [0.5.21] - 2026-11-10
+
+### Added
+- **Agent progress streaming through the execution log and SSE, external contribution (#95)**: `xflow workflow run` now streams live agent progress — `codex exec --json` and `claude --output-format stream-json --verbose` feed the execution log as the event bus, `entry_hash` is the resume token, and `xflow serve` pushes the stream over SSE. Appends no longer re-read the whole file (tail cache + 16 KB tail read, expanding to a full line when the last entry exceeds the window); a >16 KB last entry no longer breaks the hash chain on a cold cache. Test evidence: 32/32 across the four affected test files (`test/agent-stream.test.js`, `test/log-tail.test.js`, `test/execution-log.test.js`, `test/server.test.js`) locally; demo `node scripts/demo-agent-stream.mjs` 5 pushed / 5 written / 5 received over SSE, latency 16–419 ms; PR CI runs verify 42761169188 and ledger 42761169204 both pass on the final HEAD; merged main CI run 42762022933 success.
+
+Milestone M4 "lite fast track" — **not yet accepted**: this release ships no M4 slice; slices 1–4 remain merged checkpoints and the wall-clock verdict still awaits bench numbers. This release makes no M4 acceptance claim.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2 / P1-3 / P2-1 / P2-3 still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), which is at 98/135 with the 15th relaunch in flight. No bench numbers are claimed in this release.
+
+## [0.5.20] - 2026-11-10
+
+### Added
+- **M4 slice 3: workflow run auto-selects lite (#102)**: `xflow workflow run` with no explicit flag runs the slice-1 classifier first and picks the track itself — small diff → lite (spec ritual skipped, seal + replay only), big diff → full, explicit `--lite` / `--full` always wins (both flags together resolve to full), classifier failure falls back to full and records the failure, never silently lite. The decision rides in the workflow events as `lite_track_decision` (`{source, track, reason, files, added, removed, total, base, force_full}`, source `auto` / `explicit-lite` / `explicit-full` / `auto-fallback-full`), next to slice 1's `lite_fast_track` field; the CLI prints `Lite fast track: <source> → <track>`. Test evidence: 19 new tests in `test/lite-track-auto.test.js` (resolver, flag priority, executor event recording with mock atoms, CLI dry-run wiring) RED→GREEN; PR CI runs verify 42702996913 (3m31s) and ledger 42702997046 (8s) both pass; merged main CI run 42703634292 success.
+- **M4 slice 4: classifier ignores workflow-written change artifacts (#104)**: the auto end-to-end acceptance demo on main HEAD caught a real bug — run 1 auto-decided lite and sealed the red proof, but the resume flipped to full because run 1 had rewritten the tracked `specs/changes/<id>/status.json` itself (+268/−2 lines) and the force-full rule fired on the `specs/` path. `classify_repo` in `xflow/atoms/lite_track.py` now excludes workflow-generated artifacts under `specs/changes/<id>/` (`status.json`, `verify_proof.json`, `spec_delta_review.json/.md`, `tdd/`, `cr/`) from the measured stats before the verdict; human-authored spec files (`proposal.md` / `plan.md` / `tasks.md`) still force full. Test evidence: 4 new classifier unit tests in `test/lite-track.test.js` (status.json churn, generated proof artifacts, proposal.md still forces full, committed status.json churn) 4/4 fail without the fix and 4/4 pass with it; new end-to-end regression test `test/lite-track-auto-acceptance.test.js` (real small fix, no flag, red → fix → resume stays lite with `source: auto, track: lite` in both runs' events, seal + clean replay with binding hash; 400-line control stays auto-full across resume) fails on main HEAD before the fix and passes after it; full `npm run verify` exit 0 — 61 test files, 560 tests, 559 pass, 0 fail (1 skipped); PR CI runs verify 42722307306 (3m31s) and ledger 42722307186 (8s) both pass; merged main CI run 42722893282 success.
+
+Wall clock, stated plainly as preliminary (docs/evidence/m4-slice4-auto-resume.md, n=1 per track, same auto demo flow, Linux VM / node v24.22.1 / python 3.12.3): auto demo lite 4,995 ms vs full 6,363 ms (ratio 0.785) isolated, and lite 8,239 ms vs full 7,124 ms (ratio 1.157) inside `npm run verify`; the slice-2 demo re-measured 1.291 in the same suite run. Same demo, same machine, ratios 0.785–1.291 minutes apart — n=1 demo timings are dominated by per-process startup and machine load (the suite runs test files in parallel), not by the spec ritual. The formal ≤1.3× verdict for issue #5 P1-2 waits for the bench full-matrix numbers; P1-2 stays unticked, and this release makes no ≤1.3× claim.
+
+Milestone M4 "lite fast track" — **not yet accepted**: slices 1–4 are merged checkpoints; the auto end-to-end acceptance is now demonstrated (real small change through auto-lite across the red→green resume, real large change judged auto-full, seal + clean replay), but the wall-clock verdict still awaits bench numbers. This release makes no M4 acceptance claim.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2 / P1-3 / P2-1 / P2-3 still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), which is at 82/135 with the 12th relaunch in flight. No bench numbers are claimed in this release.
+
 ## [0.5.19] - 2026-11-10
 
 ### Added

package/RELEASE_NOTES.md

@@ -1,5 +1,29 @@
 # Release Notes
 
+## 0.5.21 - Agent progress streaming (external contribution #95)
+
+Patch release. One merged PR since 0.5.20, verified end to end in CI and locally.
+
+**Agent progress streaming through the execution log and SSE (#95, author MAOLVLHL).** `xflow workflow run` now streams live agent progress: `codex exec --json` and `claude --output-format stream-json --verbose` feed the execution log as the event bus, `entry_hash` is the resume token, and `xflow serve` pushes the stream over SSE. Appends no longer re-read the whole file (tail cache + 16 KB tail read, expanding to a full line when the last entry exceeds the window); a >16 KB last entry no longer breaks the hash chain on a cold cache (verified with a cold-cache reproduction: a fresh process appending after a 20 KB entry keeps the chain intact). Test evidence: 32/32 across the four affected test files locally; demo `node scripts/demo-agent-stream.mjs` 5 pushed / 5 written / 5 received over SSE, latency 16–419 ms; PR CI runs verify 42761169188 and ledger 42761169204 both pass on the final HEAD; merged main CI run 42762022933 success. Maintainer fix on the branch: the author's fix commit had dropped the executable bit on `bin/xflow.js`, breaking one CLI usability test — restored mode-only (commit fcd81d8) before merge.
+
+Milestone M4 "lite fast track" — **not yet accepted.** This release ships no M4 slice; the wall-clock verdict still awaits bench numbers.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2, P1-3, P2-1 and P2-3 — the wall-clock/token/resolved lines from issue #5 — still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), which is at 98/135 with the 15th relaunch in flight. No bench numbers are claimed in this release.
+
+## 0.5.20 - M4 lite fast track, slices 3–4 (milestone M4 not yet accepted)
+
+Patch release. Two merged PRs since 0.5.19, both verified end to end in CI and locally.
+
+**M4 slice 3: workflow run auto-selects lite (#102).** `xflow workflow run` with no explicit flag runs the classifier first and picks the track itself — small diff → lite, big diff → full, explicit `--lite` / `--full` always wins, classifier failure falls back to full and records it. The decision is written into the workflow events as `lite_track_decision`, next to `lite_fast_track`. Test evidence: 19 new tests in `test/lite-track-auto.test.js` RED→GREEN; PR CI runs verify 42702996913 and ledger 42702997046 both pass; merged main CI run 42703634292 success.
+
+**M4 slice 4: classifier ignores workflow-written change artifacts (#104).** The auto end-to-end acceptance demo on main HEAD caught a real bug: run 1 auto-decided lite and sealed the red proof, but the resume flipped to full because run 1 had rewritten the tracked `specs/changes/<id>/status.json` itself (+268/−2 lines) and the force-full rule fired on the `specs/` path. `classify_repo` now excludes workflow-generated artifacts under `specs/changes/<id>/` (`status.json`, `verify_proof.json`, `spec_delta_review.*`, `tdd/`, `cr/`) from the measured stats; human spec files still force full. Test evidence: 4 new classifier unit tests RED→GREEN (4/4 fail without the fix); new end-to-end regression test `test/lite-track-auto-acceptance.test.js` (real small fix, no flag, resume stays lite; 400-line control stays auto-full) fails before the fix, passes after; full `npm run verify` exit 0 — 61 test files, 560 tests, 559 pass, 0 fail; PR CI runs verify 42722307306 and ledger 42722307186 both pass; merged main CI run 42722893282 success.
+
+Wall clock, stated plainly as preliminary (docs/evidence/m4-slice4-auto-resume.md, n=1 per track, same auto demo flow, Linux VM / node v24.22.1 / python 3.12.3): auto demo lite 4,995 ms vs full 6,363 ms (ratio 0.785) isolated, lite 8,239 ms vs full 7,124 ms (ratio 1.157) inside `npm run verify`; slice-2 demo re-measured 1.291 in the same suite run. Same demo, same machine, ratios 0.785–1.291 — n=1 demo timings are dominated by startup and machine load, not by the spec ritual. The formal ≤1.3× verdict for issue #5 P1-2 waits for the bench full-matrix numbers; P1-2 stays unticked, and this release makes no ≤1.3× claim.
+
+**Milestone M4 "lite fast track" — not yet accepted.** Slices 1–4 are merged checkpoints; the auto end-to-end acceptance is now demonstrated (real small change through auto-lite across the red→green resume, real large change judged auto-full, seal + clean replay), but the wall-clock verdict still awaits bench numbers.
+
+Acceptance debt, stated plainly: the bench-number acceptance for P1-2, P1-3, P2-1 and P2-3 — the wall-clock/token/resolved lines from issue #5 — still awaits the MiniMax full-matrix batch (15 instances × 4 arms × reps 3), at 82/135 with the 12th relaunch in flight. No bench numbers are claimed in this release.
+
 ## 0.5.19 - M4 lite fast track, slices 1–2 (milestone M4 not yet accepted)
 
 Patch release. Two merged PRs since 0.5.18, both verified end to end in CI and locally.

package/bin/xflow.js

@@ -42,6 +42,7 @@ import { createHash } from 'crypto';
 import { tmpdir } from 'os';
 import { ackPendingGate } from '../src/core/pending-gates.js';
 import { runAudit, renderAuditReport } from '../src/core/audit.js';
+import { readEntriesFromOffset, readExecutionLogSize } from '../src/core/log-tail.js';
 import { exportDomRectsToFile, resolveCliPath } from '../src/agent_team/atoms/visual/dom-rect-export.js';
 import { capturePageEvidence } from '../src/agent_team/atoms/visual/page-evidence-capture.js';
 import { computeImageDiffMetrics } from '../src/agent_team/atoms/visual/image-diff.js';
@@ -5478,6 +5479,21 @@ async function handleWorkflow(sub, args) {
         }
       }
       ensureChangeId(changeId, 'workflow run', projectRoot);
+      // M4 slice 3 (evalid #101): auto-select the lite track. With no
+      // explicit flag the classifier decides (small diff -> lite, big diff
+      // -> full, classifier failure -> full); --lite / --full always win.
+      // The decision is attached to the workflow input so the executor
+      // records it in the workflow_started / workflow_completed events.
+      const { decideLiteTrack, resolveLiteTrackAuto } = await import('../src/core/lite-track-auto.js');
+      const autoDecision = (parsedArgs.lite === true || parsedArgs.full === true)
+        ? null
+        : resolveLiteTrackAuto({ projectRoot });
+      const { lite: effectiveLite, decision: liteDecision } = decideLiteTrack({
+        lite: parsedArgs.lite, full: parsedArgs.full, autoDecision,
+      });
+      if (effectiveLite) input.lite = true;
+      input.lite_track_decision = liteDecision;
+      console.log(`Lite fast track: ${liteDecision.source} → ${liteDecision.track} (${liteDecision.reason})`);
       const { load, dryRun } = await import('../src/core/workflow-loader.js');
       if (isDryRun) {
         dryRun(yamlPath);
@@ -5493,7 +5509,12 @@ async function handleWorkflow(sub, args) {
           changeId,
           input,
         });
-        await executor.run();
+        const progress = args.includes('--progress') ? startProgressTail(projectRoot) : null;
+        try {
+          await executor.run();
+        } finally {
+          if (progress) await progress.stop();
+        }
       }
       break;
     }
@@ -5523,6 +5544,72 @@ async function handleWorkflow(sub, args) {
   }
 }
 
+// ─── progress tail ────────────────────────────────────────────────────────────
+
+const PROGRESS_TICK_MS = 200;
+
+/**
+ * Follow the execution log on stderr while a workflow runs.
+ *
+ * Opt-in (`--progress`) so the default CLI output stays byte-identical, and stderr-only so it
+ * cannot corrupt anything a caller pipes out of stdout.
+ */
+function startProgressTail(projectRoot, { tickMs = PROGRESS_TICK_MS } = {}) {
+  let offset = null;
+  let stopped = false;
+  let draining = Promise.resolve();
+
+  const drain = async () => {
+    if (offset === null) offset = await readExecutionLogSize(projectRoot);
+    // A run that emits faster than one tick writes more than a single batch, so keep reading
+    // until the log is caught up: one capped read left the tail of a chatty run unprinted.
+    for (;;) {
+      const from = offset;
+      const batch = await readEntriesFromOffset(projectRoot, from, { limit: 100 });
+      offset = batch.nextOffset;
+      for (const entry of batch.entries) {
+        process.stderr.write(`${formatProgressEntry(entry)}\n`);
+      }
+      // Stop when the log is caught up, or when the last batch could not advance past a
+      // half-written entry (re-read on the next tick or on shutdown).
+      if (!batch.hasMore || offset <= from) return;
+    }
+  };
+
+  draining = drain().catch(() => {});
+  const timer = setInterval(() => {
+    if (stopped) return;
+    draining = draining.then(drain).catch(() => {});
+  }, tickMs);
+
+  return {
+    async stop() {
+      stopped = true;
+      clearInterval(timer);
+      await draining.catch(() => {});
+      // Drain whatever was written between the last tick and shutdown.
+      await drain().catch(() => {});
+    },
+  };
+}
+
+function formatProgressEntry(entry) {
+  const time = String(entry.timestamp || '').slice(11, 19);
+  if (entry.kind === 'agent_event') {
+    const detail = entry.tool || entry.text || entry.reason || entry.event_type || '';
+    return `[progress] ${time} agent ${entry.event}${detail ? ' · ' + singleLine(detail) : ''}`;
+  }
+  const subject = entry.atom_id || entry.phase_id || null;
+  const parts = [entry.kind || 'event'];
+  if (subject && subject !== entry.kind) parts.push(subject);
+  if (entry.status) parts.push(entry.status);
+  return `[progress] ${time} ${parts.join(' ')}`;
+}
+
+function singleLine(value) {
+  return String(value).replace(/\s+/g, ' ').slice(0, 120);
+}
+
 const CORPS_PROOF_ARTIFACTS = [
   'status.json',
   'proposal.md',
@@ -6688,15 +6775,25 @@ function printWorkflowHelp() {
 Usage: xflow workflow <command>
 
 Commands:
-  run <yaml|yolo|corps>       Run a workflow (add --dry-run to preview)
+  run <yaml|yolo|corps>       Run a workflow (add --dry-run to preview,
+                              --progress to follow agent events on stderr)
   validate <yaml|yolo|corps>  Validate workflow YAML as preflight only
 
 Options:
   --lite                  M4 lite fast track: skip spec-ritual steps
                           (proposal-consistency-check phase, J4a/J4b atoms)
-                          and keep seal + replay only. Run the classifier
-                          first (python3 xflow/atoms/lite_track.py --repo .)
-                          and add --lite only when it says lite.
+                          and keep seal + replay only. Always wins over the
+                          auto verdict (see below).
+  --full                  M4 lite fast track: force the full track, skipping
+                          the auto verdict. Wins over --lite when both are
+                          given.
+                          With neither --lite nor --full, the run classifies
+                          the working-tree diff first
+                          (python3 xflow/atoms/lite_track.py --repo .)
+                          and auto-selects lite for a small diff, full for a
+                          big one; a classifier failure falls back to full.
+                          The decision is printed and recorded in the run's
+                          workflow events as lite_track_decision.
   help, -h, --help Show this help message
 `);
 }

package/docs/evidence/m4-slice4-auto-resume.md

@@ -0,0 +1,96 @@
+# M4 slice 4: auto-lite resume flips to full on workflow-written status.json
+
+Date: 2026-11-10 (Asia/Singapore). Source of truth for the demo itself is
+`test/lite-track-auto-acceptance.test.js` (re-run it to reproduce).
+Parent issue: #97; slice issue: #103; PR: slice 4 (this change).
+
+## Status: preliminary wall clock — NOT the ≤1.3× conclusion
+
+The wall-clock numbers below are local n=1 measurements of the acceptance
+demo harness. The formal wall-clock verdict for issue #5 P1-2 (small tasks
+≤1.3× baseline) waits for the bench full-matrix numbers; P1-2 stays
+unticked and no ≤1.3× claim is made here.
+
+## The bug (found by the auto acceptance demo on main HEAD 4668b6ab)
+
+A real small fix through `xflow workflow run` with **no flag**: run 1
+(pre-fix, clean tree) auto-decides lite, seals the red proof, stops at
+tdd-green. The fix is applied, run 2 (resume) re-runs the classifier —
+and flips to **full**:
+
+| Run | `lite_track_decision` (from the workflow events) | `lite_fast_track` |
+| --- | --- | --- |
+| Run 1, pre-fix | `{source: auto, track: lite, reason: 'empty diff: nothing to ritualise', files: 0, total: 0}` | `true` |
+| Run 2, resume (pre-fix code) | `{source: auto, track: full, reason: 'touches specs/ paths (specs/changes/chg-m4-auto-demo/status.json): spec/workflow drift needs the full track', files: 3, total: 281}` | `false` |
+
+Root cause: run 1 rewrites the tracked
+`specs/changes/<id>/status.json` itself (stage transitions +
+`workflow_integrity` block, +268/−2 lines in the demo; the worktree diff
+at resume time is 3 files, 277 insertions / 13 deletions). The classifier
+measures the worktree diff against the merge-base, sees a `specs/` path,
+and the force-full rule fires. The actual user change is still the same
+2-file, 20-line fix. The two halves of one change then run on different
+tracks: the resume re-executes the spec ritual (J4a/J4b) that run 1
+skipped.
+
+Scope note: evalid's own repo gitignores `specs/changes/`, so dogfooding
+does not hit this — but any repo that tracks change state does, and the
+repo's own acceptance demo (the M4 bar) fails on main HEAD. The defect is
+in the shipped classifier, not the demo, so the fix is in the classifier.
+
+## The fix
+
+`classify_repo` in `xflow/atoms/lite_track.py` now excludes
+workflow-generated artifacts under `specs/changes/<id>/` from the measured
+stats before the verdict: `status.json`, `verify_proof.json`,
+`spec_delta_review.json` / `.md`, and the `tdd/` / `cr/` trees.
+Human-authored spec files (`proposal.md` / `plan.md` / `tasks.md`) still
+force full. No CLI / executor / env / phanes call-surface change.
+
+## Numbers (post-fix demo runs, n=1 each, preliminary)
+
+| Run | lite (first + resume) | full (first + resume) | lite/full |
+| --- | --- | --- | --- |
+| Auto acceptance test, isolated | 2,446 ms + 2,549 ms = 4,995 ms | 2,854 ms + 3,509 ms = 6,363 ms | 0.785 |
+| Auto acceptance test, inside `npm run verify` | 4,135 ms + 4,104 ms = 8,239 ms | 4,126 ms + 2,998 ms = 7,124 ms | 1.157 |
+
+Same demo, same machine, two runs minutes apart: 0.785 vs 1.157. The
+slice-2 demo re-measured inside the same suite run gives 1.291 this time
+(7,655 ms vs 5,928 ms), against its original 0.644 / 0.798. The spread
+itself is the finding: n=1 demo timings are dominated by per-process
+startup and machine load (the suite runs test files in parallel), not by
+the spec ritual. Do not quote any of these ratios as the lite-track
+speedup; the formal ≤1.3× verdict still waits for the bench full-matrix
+numbers.
+
+Machine for all runs above: Linux x86_64 VM, AMD EPYC 9D25, 4 vCPU;
+node v24.22.1, python 3.12.3.
+
+## What the demo proved (functional, not timing)
+
+- Post-fix resume decision: `{source: auto, track: lite, reason:
+  'within thresholds (2 files, 20 lines <= 10 files, 300 lines)',
+  files: 2, added: 9, removed: 11, total: 20, force_full: []}` — the
+  resume stays lite on the same fix that run 1 lite'd.
+- Lite run: `proposal-consistency-check` logged `phase_skipped` (reason
+  `lite_track`); `J4a` / `J4b` logged `atom_skipped` (reason
+  `lite_track`); the `verify-consistency` gate passed with verdict
+  `lite_skipped`; `workflow_completed` recorded `lite_fast_track: true`
+  with the auto decision in both `workflow_started` and
+  `workflow_completed`.
+- Seal + clean replay: red proof `passed: false`; green proof
+  `passed: true` with binding hash `8f5f78b44be55c3d` and snapshot scope
+  (`lite_track.py`, `test/demo.test.mjs`); I6b validated both; I6d, I6c,
+  J1 and J6 all passed.
+- Full control (400-line file staged, no flag): first run auto-full
+  (`400 lines > 300 max_lines`, 1 file), resume auto-full (420 lines,
+  3 files); J4a / J4d / J4b all executed and passed; no `lite_track`
+  skip anywhere; `workflow_completed` recorded `lite_fast_track: false`.
+
+## Reproduce
+
+```sh
+node --test test/lite-track-auto-acceptance.test.js  # prints [m4-auto-*] lines
+node --test test/lite-track.test.js                   # classifier unit tests
+npm run verify                                        # full suite
+```

package/docs/launch-dossier.md

@@ -117,7 +117,7 @@ Evidence:
 - Adoption records: 1; status: pass
 - Goal audit: pass; goal: Keep evalid credible as an open-source agent delivery runtime: repo-owned workflow contracts, executable verification gates, durable project context, and honest benchmark evidence.
 - Package evidence: missing; source: registry_json
-- Package name/version: @surlymochan/evalid@0.5.19
+- Package name/version: @surlymochan/evalid@0.5.21
 
 ## Passing Evidence
 

package/docs/workflow-manual.md

@@ -17,7 +17,8 @@
 9. [CLI 参考](#9-cli-参考)
 10. [本地 Release Checklist](#10-本地-release-checklist)
 11. [环境变量](#11-环境变量)
-12. [常见问题](#12-常见问题)
+12. [实时事件流（agent 进度）](#12-实时事件流agent-进度)
+13. [常见问题](#13-常见问题)
 
 ---
 
@@ -1077,7 +1078,109 @@ sh xflow/scripts/check_installed_xflow_skill_sync.sh
 
 ---
 
-## 12. 常见问题
+## 12. 实时事件流（agent 进度）
+
+`agent_invoke` 一次调用默认最长 300 秒（heavy CLI 1800 秒），期间 agent 的 stdout 以前只累加进字符串，运行结束时才有一条 `atom_run`。现在这段时间里发生的事会以 `agent_event` 条目写入 `.as-xflow/logs/execution.ndjson`，并通过 `/api/events` 增量推给看板。
+
+### 数据通路
+
+```
+codex exec --json  /  claude -p --output-format stream-json
+        │  stdout（NDJSON，逐行）
+        ▼
+src/core/agent-stream.js   createLineSplitter → normalizeAgentEvent → 200ms 合并
+        │  appendExecutionLog({ kind: 'agent_event', … })
+        ▼
+.as-xflow/logs/execution.ndjson   （既有 hash 链，一条一条追加）
+        │  src/core/log-tail.js   readEntriesFromOffset(offset)
+        ▼
+GET /api/events   event: log, id: <entry_hash>
+```
+
+写入侧只做归一化与截断，读侧只做字节偏移 tail；两侧都复用既有的执行日志，没有新增文件、没有新增依赖。
+
+只有能逐行输出 NDJSON 的 adapter 会接上这条通路：`codex_cli`（`codex exec --json`）与 `claude_cli`（`claude -p --output-format stream-json`）。`pencil_cli` 没有对应的 JSON 行协议，`stub` 根本没有子进程，因此这两者不产生 `agent_event`，其进度只能看到 phase/atom 级的 `atom_run` 记录——这是刻意的，不是遗漏。
+
+### 事件类型
+
+| event | 来源 | 关键字段 |
+|---|---|---|
+| `agent_start` | codex `thread.started` / claude `system:init` | `adapter` |
+| `tool_start` | codex `item.started`：`command_execution`(→ `tool`=`shell`)、`mcp_tool_call`、`file_change`、`web_search`；claude `tool_use` | `event_type`(CLI 原始 item 类型), `tool`, `args_preview`(≤160 字符), `args_digest`(sha256 前 16 位) |
+| `tool_end` | codex `item.completed` 的同四种 item 类型（`event_type` 区分）；claude 侧没有配对事件 | `event_type`, `tool`, `exit_code`, `status` |
+| `message_end` | codex `agent_message` / claude assistant `text` | `text`(≤2048 字符，超出以 `…` 结尾) |
+| `agent_end` | codex `turn.completed` / claude `result` | `usage`{`input`,`output`,`cache_read`,`cache_write`}, `cost_usd`, `duration_ms` |
+| `raw` | 无法识别、无法解析、或超长被截断的行；CLI 报错（`turn.failed` / `error`） | `reason`(`invalid_json` / `non_object_payload` / `line_truncated`), `event_type`, `level`(`error`), `truncated` |
+
+每条记录的完整形状：
+
+```json
+{
+  "timestamp": "2026-11-09T04:12:33.412Z",
+  "kind": "agent_event",
+  "event": "tool_start",
+  "phase": "implementation",
+  "atom": "I6a.tdd.run",
+  "adapter": "codex_cli",
+  "seq": 3,
+  "event_type": "command_execution",
+  "tool": "shell",
+  "args_preview": "npm test",
+  "args_digest": "9f2c1e0b7d4a5c88",
+  "change_id": "chg-124",
+  "mission_id": "mis-9",
+  "prev_hash": "…",
+  "entry_hash": "…"
+}
+```
+
+未知的 CLI 事件类型一律降级为 `raw` 或被忽略，不抛错：CLI 升级不会让整条 workflow 失败。
+
+### 订阅
+
+```javascript
+const events = new EventSource('/api/events');
+const seen = new Set();
+
+events.addEventListener('snapshot', () => { /* 首帧仍是全量快照，可整体重置 UI */ });
+events.addEventListener('log', (message) => {
+  const entry = JSON.parse(message.data);
+  if (entry.entry_hash && seen.has(entry.entry_hash)) return;  // 快照与增量可能重叠
+  if (entry.entry_hash) seen.add(entry.entry_hash);
+  renderActivity(entry);
+});
+```
+
+- 首帧永远是 `event: snapshot`（与旧行为一致），之后才是增量。
+- 增量帧带 `id: <entry_hash>`；浏览器断线重连会自动带上 `Last-Event-ID`，服务端据此回放缺失条目，不丢也不重。
+- 若该 id 对应的日志已被删除或轮转，服务端回退为正常跟随（客户端拿不到历史，只收到之后的新条目）。
+- `event: snapshot` 仍然每 3 秒重发一次。增量流只解决了“一条条新条目怎么到达”，没有取消全量快照：看板的 summary、pending gates、pending tasks 都由快照刷新，增量帧里没有这些字段。也就是说常驻连接的主要带宽仍是快照；要再降，需要把 summary/gates 也改成增量事件，那是另一个 PR 的边界。
+- 排序一律以文件顺序为准，不要用 `timestamp` 排序：同一毫秒内可能有多条。
+
+### CLI 进度输出
+
+```bash
+CHANGE_ID=<id> xflow workflow run workflows/yolo.yaml --progress
+```
+
+`--progress` 是 opt-in 的：不加时终端输出与以前逐字节一致。开启后每 200ms 把新条目打印到 stderr（stdout 留给 workflow 自己的输出），例如：
+
+```
+[progress] 12:13:02 agent tool_start · shell
+[progress] 12:13:41 agent message_end · Tests pass; writing the artifact.
+[progress] 12:13:44 atom_run I6a.tdd.run completed
+```
+
+### 性能约束
+
+- 写入：每 200ms 合并一次，单条 `text` ≤2048 字符、`args_preview` ≤160 字符；队列上限 500，超出丢最旧条目并计入 `stats.dropped`。
+- 读取：只从字节偏移往后读，单次 ≤4MB；未写完的尾行留到下次；游标只停在换行边界。
+- 哈希链：追加时从文件尾部 16KB 起求 `prev_hash`；若窗口里没有完整行（单条记录大于 16KB），窗口按 4 倍扩大直到找到为止，否则会写出 `prev_hash: null` 把链断掉。缓存按 `(size, mtimeMs)` 失效，避免同尺寸的轮转或截断命中陈旧哈希。
+- 订阅：每个 SSE 连接各自持有一个 200ms 的 tailer，一次 tick 是“stat + 从上次偏移读一小段”，单个看板标签页可以忽略；若将来有大量客户端同时观看同一 run，更省的形状是**一个共享 tailer 广播给所有连接**（当前版本未做）。
+
+---
+
+## 13. 常见问题
 
 ### workflow 停在 human gate 怎么恢复？
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@surlymochan/evalid",
-  "version": "0.5.19",
+  "version": "0.5.21",
   "description": "Claimed != verified: a runtime verification layer for coding agents. It seals each test run and replays it from a clean snapshot, with a zero-judge gate pipeline (spec clarification, code review, TDD proof) and the xflow CLI.",
   "keywords": [
     "ai-agents",

package/scripts/demo-agent-stream.mjs

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+/**
+ * demo-agent-stream.mjs — proves the agent progress path end to end.
+ *
+ * Feeds synthetic codex events through `createAgentEventSink` (the same sink
+ * `agent_invoke` uses), then prints each one as `xflow serve` delivers it over
+ * /api/events, together with the observed latency. No agent CLI is required.
+ *
+ *   node scripts/demo-agent-stream.mjs
+ */
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import startServer from '../src/server.js';
+import { createAgentEventSink } from '../src/core/agent-stream.js';
+
+const PUSH_INTERVAL_MS = 200;
+const FIXTURE = [
+  '{"type":"thread.started","thread_id":"thread_demo"}',
+  '{"type":"item.started","item":{"id":"i1","type":"command_execution","command":"npm test"}}',
+  '{"type":"item.completed","item":{"id":"i1","type":"command_execution","command":"npm test","exit_code":0,"status":"completed"}}',
+  '{"type":"item.completed","item":{"id":"i2","type":"agent_message","text":"Tests pass; writing the artifact."}}',
+  '{"type":"turn.completed","usage":{"input_tokens":1200,"output_tokens":340}}',
+];
+
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+
+function labelOf(entry) {
+  if (entry.event === 'agent_start') return 'agent_start';
+  if (entry.event === 'agent_end') return 'agent_end';
+  if (entry.tool) return `${entry.event} ${entry.tool}`;
+  return `${entry.event} ${String(entry.text || '').slice(0, 40)}`;
+}
+
+const projectRoot = mkdtempSync(join(tmpdir(), 'xflow-demo-stream-'));
+const server = await startServer({ projectRoot, port: 0 });
+const base = `http://127.0.0.1:${server.address().port}`;
+const startedAt = Date.now();
+const sentAt = new Map();
+
+console.log(`[demo] project root: ${projectRoot}`);
+console.log(`[demo] dashboard:    ${base}/`);
+console.log(`[demo] pushing ${FIXTURE.length} synthetic codex events, one every ${PUSH_INTERVAL_MS}ms\n`);
+
+const sink = createAgentEventSink({
+  projectRoot,
+  changeId: 'chg-demo-stream',
+  missionId: 'mis-demo',
+  phase: 'demo phase',
+  atom: 'demo.atom',
+  adapter: 'codex_cli',
+});
+
+const streamResponse = await fetch(`${base}/api/events`);
+const reader = streamResponse.body.getReader();
+const decoder = new TextDecoder();
+const latencies = [];
+let buffer = '';
+let received = 0;
+
+const pump = (async () => {
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    let frameEnd = buffer.indexOf('\n\n');
+    while (frameEnd !== -1) {
+      const frame = buffer.slice(0, frameEnd);
+      buffer = buffer.slice(frameEnd + 2);
+      frameEnd = buffer.indexOf('\n\n');
+      // Frames carry an `id:` line first, so match the event name rather than the first line.
+      if (!frame.includes('event: log')) continue;
+      const data = frame.split('\n').find((line) => line.startsWith('data: '));
+      if (!data) continue;
+      const entry = JSON.parse(data.slice(6));
+      const label = labelOf(entry);
+      const elapsed = Date.now() - startedAt;
+      const latency = sentAt.has(label) ? Date.now() - sentAt.get(label) : null;
+      if (latency !== null) latencies.push(latency);
+      received += 1;
+      console.log(
+        `[demo] +${String(elapsed).padStart(5)}ms  ${label.padEnd(26)} ` +
+        `phase=${entry.phase} atom=${entry.atom} id=${String(entry.entry_hash).slice(0, 8)}…` +
+        (latency === null ? '' : `  latency=${latency}ms`),
+      );
+    }
+  }
+})();
+
+for (const line of FIXTURE) {
+  const entry = JSON.parse(line);
+  sentAt.set(labelOf({
+    event: entry.type === 'thread.started' ? 'agent_start'
+      : entry.type === 'turn.completed' ? 'agent_end'
+        : entry.item?.type === 'command_execution' ? 'tool_start'
+          : 'message_end',
+    tool: entry.item?.type === 'command_execution' ? 'shell' : null,
+    text: entry.item?.text,
+  }), Date.now());
+  sink.push(`${line}\n`);
+  await sleep(PUSH_INTERVAL_MS);
+}
+await sink.close();
+await sleep(500);
+await reader.cancel();
+
+const stats = sink.stats;
+console.log(`\n[demo] events pushed: ${stats.events}, written: ${stats.written}, received over SSE: ${received}`);
+if (latencies.length) {
+  const min = Math.min(...latencies);
+  const max = Math.max(...latencies);
+  console.log(`[demo] end-to-end latency (push -> SSE): min ${min}ms, max ${max}ms over ${latencies.length} events`);
+}
+console.log('[demo] open the dashboard URL above while this script runs to watch the same stream live.');
+
+await pump.catch(() => {});
+await new Promise((resolveClose) => server.close(resolveClose));
+rmSync(projectRoot, { recursive: true, force: true });