@exaudeus/workrail 3.67.0 → 3.68.1

package/docs/design/session-metrics-attribution-discovery.md

@@ -0,0 +1,319 @@
+# Session Metrics Attribution -- Hybrid Architecture Discovery
+
+**Date:** 2026-04-21
+**Status:** Discovery complete -- recommendation ready
+
+---
+
+## About This Document
+
+Human-readable artifact for sharing findings and recommendations. NOT execution truth -- workflow session notes and context variables are the durable record. Read this for understanding, not for resuming the workflow.
+
+---
+
+## Context / Ask
+
+**Stated goal (original):** Design the right hybrid architecture for attributing git metrics (LOC, files changed, commits) to a specific WorkRail session, accounting for concurrent sessions on the same branch.
+
+**Goal classification:** `solution_statement` -- prescribes a specific hybrid architecture with confidence levels and agent SHA reporting rather than describing the outcome.
+
+**Reframed problem:** Given that git attribution via branch or time-window is unreliable when sessions overlap on the same branch, what is the minimal durable record a WorkRail session needs to carry so consumers can compute accurate git metrics even under adversarial conditions?
+
+**Prior discoveries:**
+- Discovery 1: rejected agent self-reporting of LOC/files (unreliable, agents grade own homework)
+- Discovery 2: found `buildSuccessOutcome()` + `extraEventsToAppend` as the hook point for a `run_completed` event; `observation_recorded` keys are locked; no event timestamps today
+
+---
+
+## Path Recommendation
+
+**Selected path:** `design_first`
+
+**Rationale:** The goal is already a well-formed solution statement, and the codebase landscape was thoroughly covered in Discoveries 1 and 2. The dominant risk is NOT "we don't know the landscape" -- it's "we're designing the wrong concept or solving a problem that's rarer than we think." `design_first` is correct here because:
+- The specific concurrent same-branch attribution problem has not been validated as common
+- The proposed solution (agent SHA self-reporting) has the same reliability failure mode as what Discovery 1 rejected
+- The accumulation problem for commit SHAs across steps is architecturally non-trivial and hasn't been resolved
+
+---
+
+## Constraints / Anti-goals
+
+**Core constraints:**
+- `observation_recorded` has a CLOSED discriminated union key set -- extending it requires schema + handler updates
+- `mergeContext` uses SHALLOW merge semantics (locked at §18.2) -- arrays/objects are REPLACED, not merged
+- `context_set` projection uses LATEST-WINS semantics per run -- a new `context_set` with `metrics_commit_shas: ["def"]` will silently replace an earlier `["abc"]`
+- No wall-clock timestamps on events today -- `durationSeconds` is blocked on this
+- Token usage is NOT accessible at the MCP layer
+- The `buildSuccessOutcome()` function has access to `lockedIndex: SessionIndex`, which is the current session's index only -- no cross-session queries at that point
+
+**Anti-goals:**
+- Do not design for the general case (all possible attribution problems) -- focus on the specific concurrent same-branch case
+- Do not make the high-confidence path depend on agent compliance if there's an engine-side alternative
+- Do not add a new event kind just to hold data that fits in an existing mechanism with minor conventions
+
+---
+
+## Landscape Findings (Code Investigation)
+
+### Where `git_head_sha` is captured at session start
+
+`src/mcp/handlers/v2-execution/start.ts` calls `resolveWorkspaceAnchors()` before `buildInitialEvents()`. The result is passed to `buildInitialEvents()` which emits one `observation_recorded` event per observation at the end of the initial event batch. The `git_head_sha` observation uses `type: 'git_sha1'` and regex-validates the 40-char hex format.
+
+**Pattern for `run_completed`:** Mirror exactly -- capture end HEAD SHA via `resolveWorkspaceAnchors()` at the completion advance, emit an `observation_recorded` event (re-using the existing mechanism) rather than a new event kind.
+
+**CRITICAL FINDING:** `observation_recorded` events are session-scoped (no scope field -- unique among all event kinds). The dedupeKey pattern is `observation_recorded:{sessionId}:{key}`. This means a second `git_head_sha` observation would collide with the first (same dedupeKey). To capture end HEAD SHA, either:
+  (a) Use a different key (e.g., `git_head_sha_end`) -- requires schema extension
+  (b) Emit the new `run_completed` event kind with the end SHA embedded in its data
+  (c) Change the dedupeKey to include the runId so start and end can coexist
+
+Option (b) is cleanest: a `run_completed` event with `endGitSha` in its data avoids the dedupeKey collision and clearly expresses the semantic (session finished at this SHA).
+
+### What the `SessionIndex` provides at completion time
+
+`buildSessionIndex()` in `src/v2/durable-core/session-index.ts` builds a single-session index from the current session's sorted event log. It provides:
+- `runStartedByRunId`: workflow identity per run
+- `runContextByRunId`: latest context per run
+- `sortedEvents`: the full sorted event log
+
+It does NOT provide cross-session data. At the point where `buildSuccessOutcome()` runs, only the current session's truth is loaded.
+
+**Implication for concurrent session detection:** Detecting other active sessions on the same branch at completion time would require calling `LocalSessionSummaryProviderV2.loadHealthySummaries()` which is:
+1. An async, I/O-heavy operation (scans up to 200 sessions from disk)
+2. Not available as a port in `AdvanceCorePorts` today
+3. Sequential by design (to avoid hammering the file system)
+
+This operation CANNOT be done synchronously at completion time without architectural changes to make it injectable. It would add significant latency to every final advance.
+
+### The `context_set` accumulation problem -- concrete analysis
+
+`mergeContext` contract (locked at §18.2): arrays are REPLACED, not merged.
+
+```
+step 5: context_set { metrics_commit_shas: ["abc123"] }
+step 9: context_set { metrics_commit_shas: ["def456"] }
+```
+
+Result: `metrics_commit_shas` = `["def456"]` -- "abc123" is permanently lost.
+
+Fix options:
+(a) Agent always sends full accumulated list: `["abc123", "def456"]` -- relies on agent memory, fragile
+(b) New append-style event type: architecturally sound but requires new event kind, schema change, new projection
+(c) Agent accumulates in a single context key by always including previous SHAs -- workable if the step prompt explicitly instructs this pattern
+
+Option (c) is workable but brittle. Option (b) is architecturally correct but has ceremony cost.
+
+### What `run_completed` can and cannot contain (given current infrastructure)
+
+**Can contain (authoritative, engine-computed):**
+- `endGitSha` -- available at advance time via `resolveWorkspaceAnchors()`
+- `runId` -- already in scope
+- `captureConfidence` -- partially (see below)
+
+**Cannot contain (blocked on infrastructure):**
+- `durationSeconds` -- no event timestamps today; the session start time is not recorded anywhere in the event log
+- Concurrent session detection -- cross-session queries not available at completion time
+
+**Confidence level determination at completion time:**
+The only confidence test available at completion time (without new infrastructure) is:
+- Did the agent report `metrics_commit_shas`? -- check `lockedIndex.runContextByRunId`
+- Is there a git_head_sha recorded? -- check sortedEvents for `observation_recorded` with key `git_head_sha`
+
+Testing for concurrent sessions (to set `low` confidence) requires the session summary provider, which is not injectable at the advance handler level today.
+
+---
+
+## Design Candidates
+
+### Candidate A: Minimal `run_completed` event (Phase 1, shippable now)
+
+Emit a `run_completed` event in `buildSuccessOutcome()` when `newEngineState.kind === 'complete'`.
+
+**Event schema:**
+```typescript
+{
+  kind: 'run_completed',
+  scope: { runId: string },
+  data: {
+    endGitSha: string | null,           // engine-authoritative (from resolveWorkspaceAnchors)
+    startGitSha: string | null,         // extracted from observation_recorded events in lockedIndex
+    agentCommitShas: readonly string[], // copied from context metrics_commit_shas if present (may be empty)
+    captureConfidence: 'high' | 'medium' | 'none',
+    // 'high' = agentCommitShas non-empty
+    // 'medium' = start+end SHA available (branch diff usable, concurrent risk unknown)
+    // 'none' = no git context
+  }
+}
+```
+
+**Confidence logic (no cross-session query):**
+```
+if agentCommitShas.length > 0 → 'high'
+else if startGitSha && endGitSha → 'medium'
+else → 'none'
+```
+
+Note: 'low' (concurrent same-branch sessions detected) is NOT computable at advance time without new infrastructure. Drop it from Phase 1.
+
+**Accumulation problem:** Agent must send full accumulated list in each context_set. Step prompt must explicitly say "include all commit SHAs you have made so far" not "include the commit SHAs from this step."
+
+**Schema change cost:**
+- New event kind `run_completed` in `DomainEventV1Schema` discriminated union
+- New Zod schema for data
+- Update all exhaustive handlers (grep for exhaustive switches on DomainEventV1)
+- New projection `projectRunCompletedV2` to surface this event to consumers
+
+**What ships:** A `run_completed` event in the session log when a workflow completes. Consumers can compute LOC from `git diff --stat startGitSha..endGitSha`. When agent reported SHAs, use those for precise per-session attribution. When not, use the full diff with a 'medium' confidence label.
+
+**What does NOT ship:** Duration, concurrent session detection, 'low' confidence tier.
+
+---
+
+### Candidate B: `run_completed` deferred -- use context_set convention only (skip Phase 2 entirely)
+
+The Phase 1 design (Discoveries 1+2) already recommended `metrics_commit_shas` as a flat context key. The question "when does the accumulation problem matter?" deserves scrutiny:
+
+Concurrent same-branch sessions are ONLY a problem when:
+1. Two sessions are running on the SAME branch (not just concurrently in time)
+2. Both sessions are making commits
+
+In a healthy WorkRail usage pattern (worktrees, feature branches per session), concurrent sessions use different branches. The same-branch concurrency problem is a degraded operating mode, not the common case.
+
+**Recommendation:** If same-branch concurrency is rare (< 5% of sessions based on actual usage data), a `run_completed` event adds schema complexity, maintenance cost, and exhaustive-switch update burden for marginal attribution improvement. The right move is:
+1. Require actual usage data before building Phase 2 infrastructure
+2. Phase 1 (`metrics_commit_shas` flat context key) already provides the high-confidence path when agents comply
+3. Consumers can use start/end SHAs from existing `observation_recorded` events for the 'medium' confidence case -- start SHA already exists; end SHA can be added via the existing `observation_recorded` mechanism with a new dedupeKey
+
+**What ships:** Nothing new. Phase 1 convention is sufficient.
+
+**Risk:** Attribution accuracy suffers for teams using same-branch workflows. But until we have data showing this is a real usage pattern, we don't know the actual impact.
+
+---
+
+### Candidate C: Append-style event for commit SHA accumulation (Phase 2, full solution)
+
+Introduce a new event kind `commit_sha_appended` with `scope: { runId }` and `data: { sha: string, ref: string | null }`.
+
+**Semantics:** Each time the agent makes a commit and reports it, they call `continue_workflow` with an artifact or emit a `commit_sha_appended` event (via a new MCP tool or a convention on continue_workflow). The projection folds all `commit_sha_appended` events into an ordered list.
+
+**Advantage:** Solves the accumulation problem cleanly without relying on agent memory or the full-list convention.
+
+**Cost:** New event kind, new schema, new MCP tool or convention, new projection. High ceremony.
+
+**Verdict:** This is architecturally correct but over-engineered for the current problem. Worth pursuing if `commit_sha_appended` semantics turn out to be useful for more than just attribution (e.g., audit trail, PR linking). Defer until there's a concrete second use case.
+
+---
+
+## Recommended Resolution
+
+**Phase 1 (ship now):** Candidate A -- minimal `run_completed` event. Rationale:
+- Provides engine-authoritative `endGitSha` which is not available via any existing mechanism (the dedupeKey collision blocks using `observation_recorded` for end SHA)
+- The `captureConfidence` field gives consumers a clear signal about attribution reliability
+- `agentCommitShas` copied from context at completion time creates a reliable snapshot even if context is overwritten later
+- Cost is bounded: one new event kind, one new schema, exhaustive switch updates (bounded set)
+
+**Drop from Phase 1:**
+- Concurrent session detection -- needs injectable `SessionSummaryProvider` in `AdvanceCorePorts`, adds latency, unvalidated use case
+- `durationSeconds` -- blocked on event timestamps
+- 'low' confidence tier -- requires cross-session query infrastructure
+
+**Phase 2 (only if data supports it):**
+- Inject `SessionSummaryProvider` into the advance handler ports to enable concurrent session detection
+- Emit 'low' confidence when concurrent same-branch sessions are detected
+- Requires measuring actual same-branch concurrency rate first
+
+**Accumulation fix (required alongside Candidate A):**
+The step prompt convention in `docs/authoring-v2.md` MUST say: "When reporting commit SHAs, always include the full list of all commits made during this session, not just commits from the current step." This is the only safe fix given the shallow-merge contract.
+
+---
+
+## Open Questions
+
+1. **What is the actual same-branch concurrency rate?** The decision to build cross-session detection infrastructure depends on this. 539 time-overlapping pairs does not equal 539 branch-overlapping pairs. This data is needed before committing to Phase 2.
+
+2. **Who are the consumers of `run_completed`?** The design assumes "the console dashboard" and "external analytics." Are there internal consumers (e.g., the daemon trigger system) that would benefit from a `run_completed` event? If so, this strengthens the case for Candidate A.
+
+3. **Does the `AdvanceCorePorts` interface need to be extended for workspace anchor resolution at completion time?** No -- confirmed via code investigation. The `workspacePath` is available on `V2ContinueWorkflowInput` (the input to `handleAdvanceIntent`). Pre-resolve `endGitSha` from `input.workspacePath` before calling `executeAdvanceCore`, then pass `endGitSha: string | null` as a parameter through the call chain to `buildSuccessOutcome`. No port refactor needed.
+
+---
+
+## Decision Log
+
+### Winner: Candidate A (run_completed with agentCommitShas snapshot) -- with gitBranch addition
+
+**Why it wins:**
+- Provides engine-authoritative `endGitSha` and `startGitSha` in a single self-contained event
+- `agentCommitShas` snapshot from context is durable (survives future context overwrites, unlike leaving SHAs only in context_set)
+- Follows `assessment_recorded` precedent (snapshots context data into event log at completion time)
+- Fully reversible: if agent compliance is poor, consumers can ignore `agentCommitShas` and fall back to 'medium' -- no schema change needed
+- Incremental cost over the endGitSha-only variant is trivial (one field + superRefine + sha1 validation)
+
+**Why the runner-up (endGitSha-only) lost:**
+- Would make 'high' confidence tier permanently unachievable, defeating the stated goal (concurrent same-branch disambiguation)
+- Cost difference vs. winner is negligible
+
+**Why "defer entirely" lost:**
+- No mechanism for capturing `endGitSha` without a new event kind (dedupeKey collision blocks reusing `observation_recorded`)
+- Without `endGitSha`, retrospective attribution queries break (current HEAD != session end SHA for old sessions)
+
+### Final schema (confirmed after adversarial challenge and review)
+
+```typescript
+{
+  kind: 'run_completed',
+  scope: { runId: string },
+  data: {
+    startGitSha: string | null,          // from observation_recorded events (git_head_sha key)
+    endGitSha: string | null,            // resolved at completion via input.workspacePath
+    gitBranch: string | null,            // from observation_recorded events (git_branch key)
+    agentCommitShas: readonly string[],  // sha1 validated, from context.metrics_commit_shas
+    captureConfidence: 'high' | 'medium' | 'none',
+    // 'high' = agentCommitShas non-empty (requires superRefine cross-field invariant)
+    // 'medium' = startGitSha and endGitSha available
+    // 'none' = no git context
+  }
+}
+// Zod superRefine: captureConfidence === 'high' requires agentCommitShas.length > 0
+// Zod: agentCommitShas entries validated as /^[0-9a-f]{40}$/
+```
+
+### Implementation pattern (threading fix)
+
+In `src/mcp/handlers/v2-execution/continue-advance.ts`, before calling `executeAdvanceCore`:
+```typescript
+// Lazy resolution: only resolve when session might be completing
+// (exact guard inside buildSuccessOutcome, so resolve eagerly at the advance site)
+const endGitSha: string | null = input.workspacePath
+  ? await resolveEndGitSha(ctx.v2, input.workspacePath)
+  : null;
+```
+
+Pass `endGitSha` through `executeAdvanceCore` args to `buildSuccessOutcome`. Guard emission with `newEngineState.kind === 'complete'`.
+
+---
+
+## Final Summary
+
+**Confidence band:** HIGH
+
+**Residual risks:**
+1. Agent compliance with full-accumulated-list convention is the riskiest assumption -- mitigation is authoring docs + step prompt, not architecture
+2. No specific consumer of `run_completed` identified yet -- validate before Phase 2 investment
+3. Same-branch concurrency rate unknown -- Phase 2 (concurrent detection) is data-gated on this
+
+**Phase 1 (ship without gates):**
+- `run_completed` event kind with final schema above
+- `projectSessionGitAttributionV2` pure projection
+- `ConsoleSessionSummary` extension (optional `gitAttribution` field, null-safe)
+- `docs/authoring-v2.md` update: full-accumulated-list step prompt template (REQUIRED -- feature is dead without this)
+- Consumer cross-check convention documented
+
+**Phase 2 (data-gated):**
+- Inject `SessionSummaryProvider` into `AdvanceCorePorts` for concurrent session detection
+- Add 'low' confidence tier when concurrent same-branch sessions detected
+- Gate on: same-branch concurrency rate > 5% OR measured production misattribution incidents
+
+**Phase 3 (if compliance measurement shows problem):**
+- `commit_sha_appended` append-style event type for clean SHA accumulation
+- Gate on: full-list compliance rate < 50% for multi-commit sessions
+
+**What cannot ship regardless of phase:** `durationSeconds` -- blocked on event envelope timestamps, which require a separate infrastructure change.

package/docs/design/session-metrics-candidates.md

@@ -0,0 +1,227 @@
+# Session Metrics -- Design Candidates
+
+*Raw investigative material for main agent synthesis. Not a final decision.*
+
+---
+
+## Problem Understanding
+
+**Tensions (real tradeoffs):**
+
+1. **Type safety vs. ergonomics.** Typed artifact contracts enforce schema at runtime (valuable for machine-queryable data) but require `outputContract` declarations on specific workflow steps. `context_set` is untyped but universally writeable at any step with no workflow changes.
+
+2. **Session-level vs. step-level.** Metrics (PR numbers, session outcome, files changed) are session-level outcomes. Artifacts are node-scoped by design. `context_set` is run-scoped (correct match). This is a real architectural mismatch for Candidate B.
+
+3. **Agent self-reporting reliability vs. external observation.** Git stats (LOC, files changed) computed by the agent are advisory only. Capturing the HEAD SHA at start and end and running `git diff --stat` post-hoc gives authoritative numbers -- but requires new lifecycle infrastructure.
+
+4. **Convention vs. enforcement.** A convention requires agents to follow it voluntarily. Without a schema or validation signal, agents will be inconsistent. Enforcement (artifact contract validation, auto-injected step prompts) adds ceremony but ensures consistency.
+
+**What makes this hard:**
+
+- `mergeContext` uses SHALLOW merge semantics -- nested object values are REPLACED, not merged. Using `context.metrics = {...}` as the carrier is a footgun: agents who set partial updates at different steps will silently lose earlier keys. Must use FLAT top-level keys instead.
+- The `observation_recorded` event has a CLOSED discriminated union key set. Adding new keys is not a data change -- it requires updating the TypeScript schema union, all exhaustive handlers, and documentation.
+- No event timestamps in the event envelope -- session duration is fundamentally uncomputable from the event log today, regardless of what metrics mechanism is chosen.
+- The `context_set` projection (`projectRunContextV2` and `SessionIndex.runContextByRunId`) uses LATEST-WINS semantics per run. Each agent delta completely replaces the previous context snapshot. This is fine for flat top-level keys (each key is independently addressable) but breaks nested metrics accumulation.
+
+**Likely seam:** The projection layer (`src/v2/projections/`) and the console session summary DTO (`src/v2/usecases/console-types.ts`). The capture boundary can stay unchanged; the gap is extraction and display.
+
+---
+
+## Philosophy Constraints
+
+**Principles that matter most here:**
+
+- **Prefer explicit domain types over primitives** -- `context_set` carries `JsonValue`, which is as primitive as it gets. A typed projection output (`SessionMetricsV2` interface) can add type discipline at the extraction boundary without changing the storage format.
+- **Validate at boundaries, trust inside** -- the `projectSessionMetricsV2` projection should validate and coerce context keys into typed output at the projection boundary.
+- **Exhaustiveness everywhere** -- any new event kind or `observation_recorded` key extension requires updating the discriminated union. This is a real cost, not just bureaucracy.
+- **YAGNI with discipline** -- token cost metrics are not achievable today; do not design for them. Event timestamps are infrastructure worth doing but orthogonal to this proposal.
+- **Architectural fixes over patches** -- auto-injected final step is a patch. The right architectural answer is to define a queryable projection over existing data.
+
+**Philosophy conflicts:**
+
+- Using `context_set` as a metrics carrier conflicts with "prefer explicit domain types." The conflict is manageable if the projection output is typed.
+- The `wr.contracts.metrics` approach honors "prefer explicit domain types" but conflicts with YAGNI (high ceremony for advisory data) and the session-vs-node scope mismatch makes it architecturally wrong.
+
+---
+
+## Impact Surface
+
+**Files that must stay consistent if we change the projection layer:**
+
+- `src/v2/projections/session-metrics.ts` (new) -- must consume `SortedEventLog` like other projections
+- `src/v2/usecases/console-service.ts` -- calls `projectSessionMetricsV2`, populates `ConsoleSessionSummary`
+- `src/v2/usecases/console-types.ts` -- extends `ConsoleSessionSummary` with metrics field
+- `console/src/api/types.ts` -- mirrors `ConsoleSessionSummary`; must be kept in sync
+- `docs/authoring-v2.md` -- convention must be documented for workflow authors
+- `src/v2/infra/local/session-summary-provider/index.ts` -- may need to call the new projection
+
+**Contracts that must remain consistent:**
+
+- `ConsoleSessionSummary` is a published DTO consumed by the console frontend; any new field must be backward-compatible (optional or null-safe).
+- `SortedEventLog` is the canonical input type for projections; new projection must accept it.
+
+---
+
+## Candidates
+
+### Candidate A: `context_set` convention with flat metrics keys (simplest sufficient)
+
+**Summary:** Define a documented `metrics_*` key convention at the top level of `context_set` events. Implement `projectSessionMetricsV2` to extract these keys. Add `metrics: SessionMetricsV2 | null` to `ConsoleSessionSummary`.
+
+**Tension resolution:**
+- Resolves: minimal author burden, backward-compatible, queryable with new projection, no schema change
+- Accepts: weak type safety (JsonValue storage), agent reliability (no enforcement), agents must self-compute git stats
+
+**Boundary solved at:** Projection layer -- the existing `context_set` mechanism is unchanged; only the extraction and display layers are new.
+
+**Why this boundary is best-fit:** The `isAutonomous` and `parentSessionId` precedents show that `context_set` is already the approved mechanism for session-level advisory metadata. Adding a `metrics_*` convention follows the exact same pattern. This is "validate at boundaries" -- the projection validates/coerces the advisory data into a typed interface.
+
+**Specific convention:**
+- `metrics_outcome: 'success' | 'partial' | 'abandoned' | 'error'`
+- `metrics_pr_numbers: number[]`
+- `metrics_files_changed: number` (advisory)
+- `metrics_lines_added: number` (advisory)
+- `metrics_lines_removed: number` (advisory)
+- `metrics_git_head_end: string` (advisory HEAD SHA at end; superseded by Phase 2)
+
+**Failure mode:** Agents use inconsistent key names or forget to report. Console shows null metrics for most sessions. Enforcement can be added incrementally (prompted via workflow step guidance).
+
+**Repo-pattern relationship:** Follows `projectRunContextV2` and `ConsoleSessionSummary.isAutonomous` exactly.
+
+**Gains:** Zero schema change, works for any workflow today, reversible (just remove the projection and console field).
+
+**Losses:** Weak type safety, no enforcement, agent-computed git stats are advisory.
+
+**Scope:** Best-fit for Phase 1.
+
+**Philosophy fit:** Honors YAGNI. Conflicts with "prefer explicit domain types" (JsonValue storage, mitigated by typed projection output).
+
+---
+
+### Candidate B: `wr.contracts.metrics` artifact contract (typed, validated)
+
+**Summary:** Define a new Zod-validated artifact contract `wr.contracts.metrics`, declared on a workflow's final/summary step `outputContract`. Machine-verifiable at `continue_workflow` boundary.
+
+**Tension resolution:**
+- Resolves: type safety, validation at boundary, machine-queryable via existing artifact projection
+- Accepts: author burden (outputContract required on final step), node-scoped (architectural mismatch for session-level metrics), not universal for existing workflows
+
+**Boundary solved at:** The artifact contract system (`src/v2/durable-core/schemas/artifacts/`).
+
+**Why this boundary is WRONG for this problem:** Artifacts are node-scoped (`node_output_appended` with `scope: {runId, nodeId}`). Session-level metrics don't belong to any single node. The closest existing analogs (`wr.contracts.review_verdict`, `wr.contracts.assessment`) are also node-scoped but are semantically correct there (they assess what a node did). Metrics are session-level: they describe the session outcome, not what a node did.
+
+**Failure mode:** Most workflows don't have a dedicated final/summary step. All existing workflows would need to be updated to add a final step with `outputContract: wr.contracts.metrics`. This is a high-friction migration.
+
+**Repo-pattern relationship:** Adapts the existing artifact contract pattern (correct for node-level structured outputs).
+
+**Gains:** Type safety, enforcement at boundary, reuses existing validation infrastructure.
+
+**Losses:** High author burden, wrong granularity (node vs. session), not backward-compatible.
+
+**Scope:** Too broad for Phase 1. Potentially valid as a Phase 2 opt-in (not mandatory) for workflows that want formal metrics reporting.
+
+**Philosophy fit:** Honors "prefer explicit domain types", "validate at boundaries." Conflicts with YAGNI and "minimal author burden."
+
+---
+
+### Candidate C: End-of-session HEAD SHA observation + post-hoc diff (reframe)
+
+**Summary:** Emit an additional `observation_recorded` event with key `git_head_sha_end` when the session reaches `complete` state. Add a console endpoint `GET /api/v2/sessions/:id/diff-summary` that runs `git diff --stat <start_sha>..<end_sha>` for authoritative LOC and files-changed.
+
+**Tension resolution:**
+- Resolves: agent reliability (git stats from git, not agent), no false precision, zero author burden for git metrics
+- Accepts: schema change (closed enum extension), requires git access from WorkRail at query time, complex lifecycle hook at session completion
+
+**Boundary solved at:** Two boundaries -- (1) session lifecycle (end-of-session observation emission), (2) console query layer (new endpoint).
+
+**Why this boundary is right for Phase 2 but wrong for Phase 1:** Authoritative git stats are more valuable than advisory agent-reported stats. But extending the `observation_recorded` closed enum requires a schema union update, and WorkRail currently has no git access at the MCP handler level. This is a significant but well-bounded engineering investment, appropriate as a follow-up after Phase 1 validates demand.
+
+**Specific shape:**
+- New `observation_recorded` key: `git_head_sha_end` (requires extending `DomainEventV1Schema`)
+- Emission hook: when `advanceAndRecord` produces `outcome.kind = 'advanced'` and the next snapshot state is `complete`, emit the end observation
+- Console endpoint: reads start SHA (first `observation_recorded.git_head_sha`) + end SHA (last `observation_recorded.git_head_sha_end`), runs `git diff --stat start..end`, returns JSON
+
+**Failure mode:** Extending the closed observation_recorded enum requires updating all exhaustive handlers. WorkRail has no git access today -- the console server would need to run the diff (it has access to the repo path via `repo_root` observation). Git history could be incomplete if the agent rebased between start and end.
+
+**Repo-pattern relationship:** Extends the existing `observation_recorded` start-of-session pattern.
+
+**Gains:** Authoritative git metrics, zero agent participation.
+
+**Losses:** Schema blast radius (closed enum extension), new git access boundary, complex lifecycle hook.
+
+**Scope:** Best-fit for Phase 2 (separate GitHub issue).
+
+**Philosophy fit:** Honors "architectural fixes over patches", "determinism." Conflicts with YAGNI (Phase 1 perspective).
+
+---
+
+### Candidate D: Add `timestampMs` to event envelope (foundational duration infrastructure)
+
+**Summary:** Add optional `timestampMs: number` to `DomainEventEnvelopeV1Schema`. Session duration = `last_event.timestampMs - first_event.timestampMs`.
+
+**Tension resolution:**
+- Resolves: session duration computable from event log without agent participation
+- Accepts: significant schema change, not backward-compatible for existing sessions, adds size to every event
+
+**Boundary solved at:** `DomainEventEnvelopeV1Schema` -- the lowest-level shared schema in the event log.
+
+**Why this boundary is too broad:** This is foundational infrastructure that happens to enable one metric (duration). The blast radius affects every event builder, the session index, all parsers, and the design locks doc. This is a separate engineering investment that should be proposed and decided independently.
+
+**Failure mode:** Existing sessions parse fine (optional field) but show null duration. Requires clock injection into all event builders. The design locks doc (`docs/design/v2-core-design-locks.md`) would need a new lock entry.
+
+**Repo-pattern relationship:** Departs from existing pattern (events have no timestamps today).
+
+**Gains:** Duration metrics without agent participation; future event-timing analytics.
+
+**Losses:** Significant blast radius, orthogonal scope from "metrics capture."
+
+**Scope:** Too broad for this proposal. Separate proposal: `feat(engine): add event envelope timestamps`.
+
+---
+
+## Comparison and Recommendation
+
+**Primary recommendation: Candidate A (flat keys) for Phase 1. Candidate C for Phase 2.**
+
+| Criterion | A (context_set) | B (artifact) | C (end SHA) | D (timestamps) |
+|-----------|----------------|--------------|-------------|----------------|
+| Backward compatible | ✅ | ❌ | ⚠️ | ⚠️ |
+| Author burden | minimal | high | zero | zero |
+| Type safety | projection-level | strong | git-authoritative | N/A |
+| Scope | best-fit (P1) | too broad | best-fit (P2) | separate |
+| Schema change | none | new files only | enum extension | all events |
+
+**Candidate B loses:** Session-vs-node scope mismatch is architecturally wrong. High ceremony for advisory data.
+
+**Candidate C is Phase 2:** Right solution for authoritative git stats, wrong phase (too complex for immediate need).
+
+**Candidate D is a separate proposal:** Foundational infrastructure, orthogonal to metrics capture.
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument against Candidate A:**
+
+Flat `metrics_*` keys pollute the global context namespace. A workflow author using `context.metrics_outcome` for their own purpose would silently conflict with the convention. The counter: the `metrics_` prefix is a documented namespace convention; conflicts are the author's error, not a framework deficiency.
+
+**What would tip toward Candidate B:**
+
+If the use case requires formal audit-trail compliance (e.g., billing based on LOC metrics), advisory `context_set` data is insufficient. Typed artifact contracts with validation would be necessary. No such requirement exists currently.
+
+**What would tip toward doing nothing:**
+
+If inspection of real session event logs reveals that agents ALREADY consistently self-report outcomes in step notes (plain markdown), the right solution is better console extraction of markdown content, not new capture infrastructure. This should be validated before Phase 1 implementation.
+
+**Pivoting away from flat keys:**
+
+If the context budget (`MAX_CONTEXT_BYTES = 256KB`) becomes a constraint (unlikely), or if namespace pollution proves problematic, a Phase 1.5 could introduce a lightweight `context.metrics` object with explicit full-replacement semantics (agents always send the complete object).
+
+---
+
+## Open Questions for Main Agent
+
+1. Are agents already self-reporting outcomes in step notes? (Validate primary framing risk before implementing.)
+2. Should Phase 1 include any enforcement signal (e.g., a final step prompt that asks for `metrics_*` keys), or is the convention sufficient initially?
+3. Should `metrics_git_head_end` (advisory) be included in Phase 1, or deferred to Phase 2?
+4. Is the context namespace pollution risk (flat `metrics_*` keys) acceptable, or should the convention use a namespacing strategy?

package/docs/design/session-metrics-design-review.md

@@ -0,0 +1,104 @@
+# Session Metrics -- Design Review Findings
+
+*Review findings for the selected direction: Candidate A (flat context_set keys + projectSessionMetricsV2 projection)*
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Assessment | Condition for Reversal |
+|----------|-----------|----------------------|
+| JsonValue storage, typed projection output | Acceptable. Consistent with isAutonomous/parentSessionId precedent. | If metrics_outcome drives workflow branching → migrate to typed artifact contract |
+| No enforcement, relies on step prompting | Acceptable IF prompting guidance is included. Without it, feature is functionally dead. | N/A -- enforcement is a Phase 2 enhancement |
+| Advisory git stats (LOC, files) | Acceptable with clear "agent-reported" UI labeling. | Phase 2 (Candidate C) removes this tradeoff |
+| Flat key namespace (metrics_ prefix) | Acceptable. mergeContext semantics are design-locked at §18.2. | If 20+ metrics keys make context debugging painful → introduce sub-object with explicit full-replacement semantics |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Covered | Missing Mitigation | Risk |
+|-------------|---------|-------------------|------|
+| Convention adoption near-zero without step prompting | Partially -- docs required, but template not specified | Concrete reusable step prompt template in docs/authoring-v2.md | HIGH |
+| Inconsistent key names (metrics_pr_number vs metrics_pr_numbers) | Silently returns null (acceptable) | None required for Phase 1 | LOW |
+| Nested metrics object shallow-merge footgun | NOT covered by design | Explicit WARNING in authoring docs against using nested context.metrics = {...} | MEDIUM |
+| Malformed projection values | Requires defensive coercion implementation | Projection must coerce/null, not throw, on malformed types | MEDIUM |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**From runner-up (Candidate C):** `metrics_git_head_end` should be included in Phase 1 convention as an advisory key with explicit Phase 2 upgrade path (same key, automatic source in Phase 2). No design change needed -- this is additive.
+
+**Simpler variant:** `metrics_outcome` only (single key, closed enum). Valid as a scope reduction if Phase 1 must ship quickly. Full spec is already scope-appropriate.
+
+**Hybrid:** `metrics_outcome` as the primary/required recommendation; all others optional. Already how the design is structured.
+
+**Conclusion:** No material design changes from comparison. Design is well-scoped.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|-----------|--------|
+| YAGNI | ✅ Satisfied |
+| Immutability | ✅ Satisfied |
+| Validate at boundaries | ✅ Satisfied (projection coercion) |
+| Functional/declarative | ✅ Satisfied |
+| Determinism | ✅ Satisfied |
+| Prefer explicit domain types | ⚠️ Tension -- JsonValue storage (acceptable, consistent with existing precedent) |
+| Type safety as first line of defense | ⚠️ Tension -- no compile-time guarantee on agent output (acceptable for advisory data) |
+| Make illegal states unrepresentable | ⚠️ Tension -- malformed values coerced to null (acceptable for advisory data) |
+| Architectural fixes over patches | ✅ Satisfied -- projection layer, not a special case |
+
+---
+
+## Findings
+
+### RED (Blocking or Critical)
+
+None identified. Design does not violate any hard invariants.
+
+### ORANGE (Important, Must Address Before Ship)
+
+**O1: Convention adoption requires concrete step prompt template**
+The design as specified requires a step prompt template in `docs/authoring-v2.md`. Without a copy-paste ready prompt that workflow authors can add to their final step, adoption will be near-zero and the feature will appear broken. This is a REQUIRED deliverable alongside the code changes.
+
+**O2: Explicit warning against nested metrics objects**
+The shallow merge footgun (`context.metrics = {...}` gets fully replaced on partial updates) must be explicitly warned against in the authoring docs. Without this, workflow authors who follow intuition will silently lose metric data.
+
+### YELLOW (Advisories, Can Be Addressed in Follow-Up)
+
+**Y1: Defensive projection coercion must be implemented**
+The `projectSessionMetricsV2` projection must coerce malformed values to null rather than propagating or throwing. E.g., if `metrics_pr_numbers` is the string `"123"` instead of `[123]`, return `null` for that field. Implement this defensively at the projection boundary.
+
+**Y2: Console UI must label advisory metrics**
+The console display must show "agent-reported" or equivalent label for all Phase 1 metrics to avoid false precision. Do not present advisory LOC counts as authoritative. This is a UX requirement, not a code requirement.
+
+**Y3: Document escalation trigger for type safety**
+If `metrics_outcome` is ever used to drive automated workflow behavior (conditional branching, auto-dispatch), the type-safety tension becomes critical. Document this escalation condition in the design notes so future feature work knows when to migrate to a typed artifact contract.
+
+---
+
+## Recommended Revisions
+
+1. **Add to Phase 1 scope:** A reusable final-step prompt template in `docs/authoring-v2.md` -- exact wording for a "report outcomes" step that instructs the agent to set `metrics_outcome`, `metrics_pr_numbers`, and other relevant keys. (O1)
+
+2. **Add to authoring docs:** A warning section "Do not use context.metrics = {...}" explaining the shallow merge footgun and why flat `metrics_*` keys are required. (O2)
+
+3. **Add to projection implementation spec:** Defensive coercion: all metrics fields return `null` if absent or malformed; projection never throws on bad metric values. (Y1)
+
+4. **Add to console UI spec:** Advisory labeling for all Phase 1 metrics values. "Agent-reported" tag or equivalent. (Y2)
+
+5. **Include `metrics_git_head_end` in Phase 1 convention** with documentation that this is advisory and will be superseded by automatic capture in Phase 2. (from runner-up borrowing)
+
+---
+
+## Residual Concerns
+
+1. **Primary framing risk unverified:** We have not verified whether agents are already self-reporting outcomes informally in step notes. If they are, Phase 1 may duplicate effort or conflict with existing informal conventions. **Recommendation:** Before shipping, sample 10-20 recent session event logs and check whether any `context_set` events already contain outcome-like data.
+
+2. **`metrics_git_head_end` reliability:** Agents may forget to run `git rev-parse HEAD` or may report the wrong commit (e.g., the HEAD before their final commit). Phase 1 should document this as advisory with low confidence, and Phase 2 should be prioritized to make it authoritative.
+
+3. **Console projection callsite:** `console-service.ts` calls `projectRunContextV2` today; adding a call to `projectSessionMetricsV2` is additive but adds latency to session summary loading. If metrics projection is expensive (it shouldn't be for a simple key-read), it should be lazy-loaded or cached alongside the existing summary cache.