M2 — 1.U end-to-end harness + engine-hardening pass + cross-process cost persistence

.github/workflows/ci.yml

@@ -5,7 +5,9 @@
 #
 # Branch protection (set in the GitHub repo settings, not here): the `ci` job below is the
 # REQUIRED status check to merge into `main`. The `peer-dep-gate` job is advisory until the
-# surface packages land their peers in Phase 1.
+# surface packages land their peers in Phase 1. The `coverage` job is advisory too — it enforces
+# the testing.md >=90% line+branch engine floor (exit criterion #5) but stays non-required until the
+# thin core-branch margin is confirmed stable under CI's Node 22; promote it to a required check then.
 #
 # Caching: the always-on layer is the GitHub Actions `.turbo` cache (restored/saved below),
 # which makes a no-change re-run a Turborepo cache hit — the M0 "demonstrably hitting"
@@ -129,6 +131,44 @@ jobs:
       - name: Install with strict peers
         run: pnpm install --frozen-lockfile --config.strict-peer-dependencies=true
 
+  # Engine coverage floor (testing.md >=90% line+branch, exit criterion #5). Advisory for now — a
+  # SEPARATE job (not part of the required `ci` job) so it surfaces a regression without blocking merge
+  # while the core-package branch margin is thin. `pnpm coverage` is a repo-ROOT run, which is what makes
+  # the root-relative per-glob thresholds (packages/core, packages/llm) authoritative (vitest.config.ts).
+  # Promote to a required check once the margin is confirmed stable under CI's Node 22.
+  coverage:
+    name: engine coverage floor (advisory)
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
+        with:
+          persist-credentials: false
+      - uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4.4.0
+        with:
+          node-version-file: .nvmrc
+          cache: pnpm
+      - name: Install (frozen lockfile)
+        run: pnpm install --frozen-lockfile
+      # Share the same Turborepo local cache the `ci` job writes, so the build below is a warm cache hit
+      # on a same-SHA / recent-ancestor run rather than a cold rebuild.
+      - name: Restore Turborepo cache
+        uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+        with:
+          path: .turbo
+          key: turbo-${{ runner.os }}-${{ github.sha }}
+          restore-keys: |
+            turbo-${{ runner.os }}-
+      # `pnpm coverage` is a repo-ROOT vitest run (not a turbo task), so it does NOT get the `test`
+      # task's `^build` — yet the `@relavium/*` package `exports` resolve only to `dist`. Build first so a
+      # fresh checkout can resolve the cross-package entries (a per-package test gets dist via turbo `^build`;
+      # each package still covers its OWN src via relative imports, so the floor stays src-accurate).
+      - name: Build workspaces (so coverage resolves the @relavium/* package entries)
+        run: pnpm turbo run build
+      - name: Engine coverage floor (>=90% line+branch)
+        run: pnpm coverage
+
 # --- Reserved Phase-1 lanes (TODO: enable with the first provider adapter) ------------
 # The per-provider conformance suite and the nightly live-API lane land WITH the adapters
 # in Phase 1 (testing.md); only their CI slots are reserved here so the testing standard

AGENTS.md

@@ -24,11 +24,13 @@ gateway; engine stays local, Phase 2) — split across build phase 5 (managed in
 phase 6 (cloud execution + portal); the engine is identical across all three (ADR-0012..0015).
 **Status: Phase 1 in progress — milestone M1 (LLM seam proven) reached (PR #9, 2026-06-07);**
 `@relavium/llm` (the seam + all three adapters) is landed and green. Phase 0 (M0) landed
-the monorepo + `@relavium/shared` + CI + `@relavium/db`. Since then, the ADR-0031 multimodal
-seam-shape amendment (1.AD, PR #11) and the `FallbackChain` runner (1.K, PR #13, 2026-06-11)
-have landed. Active work continues on the
-[`@relavium/core` engine](docs/roadmap/phases/phase-1-engine-and-llm.md) (1.L next); see
-[docs/roadmap/current.md](docs/roadmap/current.md).
+the monorepo + `@relavium/shared` + CI + `@relavium/db`. The
+[`@relavium/core` engine](docs/roadmap/phases/phase-1-engine-and-llm.md) has since landed the full
+run-loop + node stack — parser, interpolation, DAG/`RunPlan`, the run loop + `RunEventBus`, the tool
+registry, the `AgentRunner`, the six node-type handlers, the human gate, checkpoint/resume, node retry,
+the expression sandbox, and the pre-egress budget governor — plus the agent-first `AgentSession` (1.V),
+**completing milestone 1.m4** (PRs #13–#26). Next on the critical path is the **1.U** end-to-end Node
+harness (milestone **M2**); see [docs/roadmap/current.md](docs/roadmap/current.md) for live status.
 
 ## The non-negotiable rules
 

CLAUDE.md

@@ -38,7 +38,7 @@ A run executes in one of **three execution modes** behind the one `LLMProvider`
 engine is identical across all three. See [ADR-0012](docs/decisions/0012-managed-inference-dual-mode.md) to [ADR-0015](docs/decisions/0015-managed-mode-data-handling-and-compliance.md)
 and [docs/architecture/managed-inference.md](docs/architecture/managed-inference.md).
 
-**Status: Phase 1 in progress — milestone M1 (LLM seam proven) reached (PR #9, 2026-06-07); the `FallbackChain` runner (1.K) landed, completing 1.m2 with the cost tracker (PR #13, 2026-06-11); the run loop (1.N — `WorkflowEngine` + `RunEventBus`) landed (PR #17, 2026-06-13) **completing 1.m3** (parse → DAG → run loop emits the canonical event stream), with the built-in `ToolRegistry` (1.T, a 1.m4 component) landing alongside it as the other `AgentRunner` (1.O) join prerequisite; the **`AgentRunner` (1.O) — per-node LLM execution behind the seam — landed (PR #18, 2026-06-14)**; and the **node-type handlers (1.P) — the six non-agent `NodeExecutor` arms (condition / transform / fan_out / fan_in / input / output) behind a dispatching executor — landed (PR #20, 2026-06-14)**; and **checkpoint/resume (1.R) + the human gate (1.Q) landed (PR #22, 2026-06-15)** — the derived `Checkpointer` + cross-process `resumeFromCheckpoint`, and the `human_in_the_loop` gate with the one-shot timeout port; and **node retry (1.S) — the above-chain whole-node retry budget ([ADR-0040](docs/decisions/0040-node-retry-budget-above-the-chain.md), amending ADR-0038) — landed (PR #24, 2026-06-15)**, re-dispatching a whole node on a retryable failure up to `retry.max` attempts (with `node:retrying`, abort-aware backoff, and `retry_on` filtering), with retry-from-node (ADR-0040 Part B) deferred to Phase-2. The pre-egress budget governor (1.AC) is next, toward M2.**
+**Status:** Phase 1 in progress — milestone M1 (LLM seam proven) reached (PR #9, 2026-06-07); the `FallbackChain` runner (1.K) landed, completing 1.m2 with the cost tracker (PR #13, 2026-06-11); the run loop (1.N — `WorkflowEngine` + `RunEventBus`) landed (PR #17, 2026-06-13) **completing 1.m3** (parse → DAG → run loop emits the canonical event stream), with the built-in `ToolRegistry` (1.T, a 1.m4 component) landing alongside it as the other `AgentRunner` (1.O) join prerequisite; the **`AgentRunner` (1.O) — per-node LLM execution behind the seam — landed (PR #18, 2026-06-14)**; and the **node-type handlers (1.P) — the six non-agent `NodeExecutor` arms (condition / transform / fan_out / fan_in / input / output) behind a dispatching executor — landed (PR #20, 2026-06-14)**; and **checkpoint/resume (1.R) + the human gate (1.Q) landed (PR #22, 2026-06-15)** — the derived `Checkpointer` + cross-process `resumeFromCheckpoint`, and the `human_in_the_loop` gate with the one-shot timeout port; and **node retry (1.S) — the above-chain whole-node retry budget ([ADR-0040](docs/decisions/0040-node-retry-budget-above-the-chain.md), amending ADR-0038) — landed (PR #24, 2026-06-15)**, re-dispatching a whole node on a retryable failure up to `retry.max` attempts (with `node:retrying`, abort-aware backoff, and `retry_on` filtering), with retry-from-node (ADR-0040 Part B) deferred to Phase-2; and the **pre-egress budget governor (1.AC, [ADR-0028](docs/decisions/0028-workflow-resource-governance.md)) + the `AgentSession` agent-first entry point (1.V, [ADR-0024](docs/decisions/0024-agent-first-entry-point-agentsession.md)) landed together (PR #26, 2026-06-16)** — 1.AC was the last 1.m4 component, so **1.m4 is complete** (the full engine stack: node handlers, gate, checkpoint/resume, retry, tools, sandbox, budget governor), and 1.V opens the Lane-C agent-first sub-spine (1.m5). The end-to-end Node harness (1.U) — the **M2 critical-path milestone**, now unblocked — is next, with Lane C continuing at session events (1.W) + persistence (1.X).
 Phase 0 (M0, 2026-06-04) landed the monorepo, strict toolchain + CI, `@relavium/shared` (the
 full Zod contract set), the no-vendor-type seam fence, and `@relavium/db`. Phase 1 has since
 landed `@relavium/llm` — the `LLMProvider` seam + all three adapters (Anthropic, OpenAI/DeepSeek,
@@ -60,7 +60,9 @@ executor-only with a `secretInputNames` masking gate on `NodeExecContext`), and
 `run_events` log, no checkpoint table — ADR-0003) + cross-process `resumeFromCheckpoint` with idempotent
 re-delivery and a `workflow_mismatch` identity guard, and the `human_in_the_loop` gate's suspend/resume
 plus the one-shot `setTimer` timeout port — `approve` auto-resolves, `reject` fails with `run_timeout`).
-Active work is now the last 1.m4 workstream — the pre-egress budget governor (1.AC) — toward **M2**; see
+The last 1.m4 workstream — the pre-egress budget governor (1.AC) — and the agent-first `AgentSession` (1.V)
+landed together (PR #26, 2026-06-16), **completing 1.m4**; active work is now the **1.U** end-to-end Node
+harness (the **M2** milestone) plus Lane C's session events (1.W) + persistence (1.X); see
 [docs/roadmap/current.md](docs/roadmap/current.md). See [README.md](README.md) for the public overview.
 
 ## Non-negotiable rules for AI agents

README.md

@@ -45,7 +45,10 @@ The **run loop** (1.N — `WorkflowEngine` + `RunEventBus`) landed (PR #17, 2026
 milestone 1.m3** (parse → DAG → run loop emits the canonical event stream); the **built-in
 `ToolRegistry`** (1.T, a 1.m4 component) landed alongside it; the **`AgentRunner`** (1.O —
 per-node LLM execution behind the seam) landed (PR #18, 2026-06-14); and the **node-type handlers**
-(1.P — the six non-agent handlers behind a dispatching executor) landed (PR #20, 2026-06-14). Next on
-the critical path: the **human gate** (1.Q), checkpoint/resume and retry, plus the **AgentSession**
-runtime + export-to-workflow sub-spine. See
+(1.P — the six non-agent handlers behind a dispatching executor) landed (PR #20, 2026-06-14), followed by
+the **human gate** (1.Q) + **checkpoint/resume** (1.R, PR #22), **node retry** (1.S, PR #24), and the
+**pre-egress budget governor** (1.AC) together with the agent-first **`AgentSession`** entry point (1.V) —
+both landed in **PR #26 (2026-06-16)**. With the budget governor in, **milestone 1.m4 is complete** (the full
+engine stack); next on the critical path is the **end-to-end Node harness** (1.U) — milestone **M2** — with the
+agent-first sub-spine (session events 1.W, persistence 1.X) continuing in parallel. See
 [docs/roadmap/current.md](docs/roadmap/current.md) for live status.

docs/roadmap/current.md

@@ -2,7 +2,7 @@
 
 > Status: Living
 
-> Last updated: 2026-06-15
+> Last updated: 2026-06-16
 
 - **Related**: [README.md](README.md), [phases/phase-0-foundations.md](phases/phase-0-foundations.md), [phases/phase-1-engine-and-llm.md](phases/phase-1-engine-and-llm.md), [../project-structure.md](../project-structure.md), [../tech-stack.md](../tech-stack.md)
 
@@ -86,7 +86,9 @@ consuming `@relavium/db` for run persistence).
 
 Global milestone **M1 — LLM seam proven** is reached (PR #9, 2026-06-07): all three
 adapters pass the shared conformance suite behind the frozen seam. The next checkpoint is
-**M2 — engine end-to-end** (see the [milestone spine](README.md#global-milestone-spine)).
+**M2 — engine end-to-end**, now gated **only** by the **1.U** end-to-end Node harness — the rest
+of the engine (milestone **1.m4**) completed with the pre-egress budget governor in PR #26 (see the
+[milestone spine](README.md#global-milestone-spine)).
 
 > **One Phase-0 follow-up lives outside the code:** a maintainer should mark the CI `ci`
 > job a **required check** in GitHub branch protection (optionally adding `TURBO_TOKEN`/
@@ -155,8 +157,16 @@ auto-resolves, `reject` fails with `run_timeout`). **Node retry (1.S) is ✅ Don
 ([ADR-0040](../decisions/0040-node-retry-budget-above-the-chain.md) Part A: re-dispatch a whole node on a
 retryable, `retry_on`-admitted failure up to `retry.max` attempts with abort-aware backoff and the non-terminal
 `node:retrying`, `node:failed` staying the single terminal; the user-triggered retry-from-node Part B is
-deferred to Phase-2). The lane now continues at the last **1.m4** workstream toward **M2** — the **pre-egress
-budget governor (1.AC)** — and the agent-first sub-spine (**1.V–1.AA**, Lane C) is open now that 1.O exists.
+deferred to Phase-2). The last **1.m4** workstream — the **pre-egress budget governor (1.AC)** ([ADR-0028](../decisions/0028-workflow-resource-governance.md):
+the `BudgetGovernor` pre-egress cost gate, `on_exceed` warn/fail/pause_for_approval, `budget:warning`/`budget:paused`/`run:timeout`,
+the H3 approve-continues bypass, the per-attempt `FallbackChain` enforcement) — and the agent-first **`AgentSession`
+(1.V)** entry point ([ADR-0024](../decisions/0024-agent-first-entry-point-agentsession.md): multi-turn
+`start`/`sendMessage`/`cancel` over the shared `runAgentTurn` core, the hard turn cap → `turn_limit`, cost +
+emission via an injected `SessionEventSink`) **then landed together — ✅ Done (PR #26, 2026-06-16)**. 1.AC closed
+**1.m4** (the full engine stack), so the critical path now reaches **1.U — the end-to-end Node harness (the M2
+milestone)**, now unblocked; in parallel, **Lane C** (the 1.m5 sub-spine) continues from 1.V at **1.W** (wire the
+`SessionEventSink` onto the `RunEventBus` + per-session `sequenceNumber`/`SessionHandle`) and **1.X** (session
+persistence), with cost-event persistence still a tracked deferral.
 
 > **Multimodal I/O — the shape is landed (1.AD ✅ Done, PR #11, 2026-06-10).** First-class
 > image/audio/video I/O (input **and** output, incl. generate-media-by-rule) was decided on 2026-06-08:
@@ -186,8 +196,9 @@ budget governor (1.AC)** — and the agent-first sub-spine (**1.V–1.AA**, Lane
 > other 1.O join prerequisite; **the `AgentRunner` join (1.O) is ✅ Done (PR #18, 2026-06-14)**; and the
 > **node-type handlers (1.P) are ✅ Done (PR #20, 2026-06-14)**; **checkpoint/resume (1.R) + the
 > human gate (1.Q) are ✅ Done (PR #22, 2026-06-15)**; and **node retry (1.S) is ✅ Done (PR #24, 2026-06-15)**
-> (ADR-0040 Part A; the user-triggered retry-from-node Part B is deferred to Phase-2). The **pre-egress budget
-> governor (1.AC)** is the next workstream.
+> (ADR-0040 Part A; the user-triggered retry-from-node Part B is deferred to Phase-2); and the **pre-egress budget
+> governor (1.AC) + the `AgentSession` (1.V) entry point are ✅ Done (PR #26, 2026-06-16)** — 1.AC closed **1.m4**.
+> The next workstream is **1.U** (the end-to-end Node harness, the M2 milestone), with Lane C continuing at 1.W/1.X.
 
 Carry-over hardening is tracked in [deferred-tasks.md](deferred-tasks.md) — pick items up as Phase 1
 first touches each file.