@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/design/design-review-consolidate-dev-staleness.md

@@ -0,0 +1,54 @@
+# Design Review: Consolidate WORKRAIL_DEV_STALENESS into WORKRAIL_DEV
+
+## Tradeoff Review
+
+| Tradeoff | Status | Notes |
+|---|---|---|
+| `WORKRAIL_DEV_STALENESS` env var stops working | Acceptable | Never publicly documented; not present in any checked-in configs |
+| Per-call DI resolution instead of module-level const | Acceptable | `isDevMode()` is a map lookup; `dev-mode.ts` has fallback for uninitialized DI |
+| 5 documentation locations to update | Manageable | All identified; none in shipped user-facing docs requires backward-compat consideration |
+
+## Failure Mode Review
+
+| Failure mode | Handled | Notes |
+|---|---|---|
+| DI container uninitialized at call time | Yes | `dev-mode.ts` try/catch fallback to `process.env['WORKRAIL_DEV']` |
+| Test regression from default param change | Yes | All tests pass `devMode` explicitly; default is not exercised by tests |
+| Missing a doc update | Low risk | 5 locations identified; missing one would be cosmetic only |
+
+## Runner-Up / Simpler Alternative Review
+
+- **Runner-up (explicit call sites):** No strengths worth borrowing. Strictly more code for the same behavior.
+- **Simpler variant:** None exists. The selected approach is already the minimum change.
+
+## Philosophy Alignment
+
+All relevant principles satisfied:
+- DI for boundaries: `isDevMode()` via `IFeatureFlagProvider`
+- Determinism: flag is stable during a request
+- YAGNI: no deprecated alias kept
+- Document "why": JSDoc updated
+- Immutability: `shouldShowStaleness` signature unchanged
+
+No philosophy tensions.
+
+## Findings
+
+No red or orange findings. One yellow:
+
+**Yellow:** The design doc `docs/design/workrail-config-file-discovery.md` contains 3 references to `WORKRAIL_DEV_STALENESS` (lines 75, 147, 436). This is a historical design document, not a runtime or user-facing doc. Updating it is optional but recommended for consistency.
+
+## Recommended Revisions
+
+None required. The implementation plan is:
+1. `src/mcp/handlers/v2-workflow.ts`: Remove `DEV_STALENESS` const; change default param; add `isDevMode` import; update JSDoc on `shouldShowStaleness`.
+2. `src/config/feature-flags.ts` line 109: Update description to include staleness.
+3. `src/config/config-file.ts` lines 10 and 32: Remove `WORKRAIL_DEV_STALENESS` from comments.
+4. `AGENTS.md` line 141: Change to `WORKRAIL_DEV=1`.
+5. `docs/authoring-v2.md` line 495: Change to `WORKRAIL_DEV=1`.
+6. `docs/configuration.md` line 44: Remove `WORKRAIL_DEV_STALENESS`.
+7. (Optional) `docs/design/workrail-config-file-discovery.md`: Update 3 references.
+
+## Residual Concerns
+
+None. This is a low-risk, well-scoped change.

package/docs/design/design-review-walk-cache-depth-limit.md

@@ -0,0 +1,48 @@
+# Design Review: Walk Cache, Depth Limit, Skip Dirs, Graceful Degradation
+
+## Tradeoff Review
+
+| Tradeoff | Acceptable? | Conditions for Failure |
+|---|---|---|
+| Non-cancelling timeout | Yes | Would fail if depth limit + skip dirs didn't bound the walk; they do |
+| Module-level mutable Map cache | Yes | Would fail if Node.js were multi-threaded; it is not |
+| 30s staleness window | Yes | Would fail if users frequently create/delete .workrail dirs within 30s; unlikely |
+| listRememberedRoots returning [] | Yes | Acceptable because callers cannot recover from throws anyway |
+
+## Failure Mode Review
+
+| Failure Mode | Mitigation | Risk Level |
+|---|---|---|
+| Depth guard at wrong position | Test #8 (depth boundary) catches it | Low (test-covered) |
+| Cache key collision | `path.resolve` + sort + `\0` separator prevents it | Low |
+| Timeout error propagating out | try/catch inside `createWorkflowReaderForRequest` | Low |
+| withTimeout import path in request-workflow-reader.ts | Import as `./with-timeout.js` (same shared/ dir) | Low |
+| Existing tests poisoning cache | Unique mkdtempSync paths = different cache keys; afterEach clears | Low |
+
+## Runner-Up / Simpler Alternative Review
+
+No real runner-up. The spec fully prescribes the implementation. The selected design is already the simplest approach that satisfies all acceptance criteria.
+
+## Philosophy Alignment
+
+**Satisfied:** Errors are data, immutability (Set), document-why, validate-at-boundaries, compose with small pure functions, YAGNI.
+
+**Tensions:**
+- Module-level mutable Map: acceptable -- mutation is confined and `clearWalkCacheForTesting()` makes the boundary explicit
+- Time-dependent TTL behavior: acceptable -- documented and short
+
+## Findings
+
+**Yellow (advisory):**
+1. The depth guard MUST be placed INSIDE the loop, AFTER the `.workrail` entry check, BEFORE the recursive call. Placing it at the top of the function would miss `.workrail` entries at exactly depth 5. This is the highest-risk implementation detail.
+2. The timeout try/catch must wrap ONLY the `discoverRootedWorkflowDirectories` call, not the entire `createWorkflowReaderForRequest` function body.
+
+**No Red or Orange findings.** The design is straightforward and well-bounded.
+
+## Recommended Revisions
+
+None. Proceed with implementation as planned.
+
+## Residual Concerns
+
+- The background walk after timeout could theoretically consume file handles on very large repos with many remembered roots. The depth limit and skip dirs list mitigate this significantly. Not a concern in practice for the expected workload.

package/docs/design/implementation-plan-consolidate-dev-staleness.md

@@ -0,0 +1,142 @@
+# Implementation Plan: Consolidate WORKRAIL_DEV_STALENESS into WORKRAIL_DEV
+
+## Problem Statement
+
+Two separate dev flags exist:
+- `WORKRAIL_DEV=1` -- controls perf timing and the perf console endpoint via DI `isDevMode()`
+- `WORKRAIL_DEV_STALENESS=1` -- controls staleness visibility for all workflow categories via a direct `process.env` read in `src/mcp/handlers/v2-workflow.ts`
+
+The module-level `DEV_STALENESS` const bypasses the DI-injected feature flag system, making it inconsistent with other dev features and preventing it from being set via `~/.workrail/config.json`.
+
+## Acceptance Criteria
+
+1. `WORKRAIL_DEV=1` enables staleness visibility for all workflow categories (including built-in and legacy_project).
+2. `WORKRAIL_DEV_STALENESS` env var is no longer supported (silently ignored if set).
+3. `npx vitest run` passes with no new failures.
+4. `npm run build` compiles cleanly.
+5. All documentation references to `WORKRAIL_DEV_STALENESS` are updated to `WORKRAIL_DEV`.
+
+## Non-Goals
+
+- Backward compatibility for `WORKRAIL_DEV_STALENESS` (never publicly documented).
+- Updating worktree copies of affected files (separate branches).
+- Any change to the `shouldShowStaleness()` public API or its explicit test coverage.
+
+## Philosophy-Driven Constraints
+
+- **DI for boundaries** -- no raw `process.env` reads in handler code for feature flags.
+- **YAGNI** -- no deprecated alias for `WORKRAIL_DEV_STALENESS`.
+- **Immutability** -- `shouldShowStaleness()` signature unchanged (optional `devMode` param stays).
+- **Document "why"** -- JSDoc updated to explain consolidation.
+
+## Invariants
+
+- `shouldShowStaleness()` remains exported and its signature is unchanged.
+- Tests that pass `devMode` explicitly continue to work unchanged.
+- Call sites that pass no second arg now get `isDevMode()` as the effective default.
+- `isDevMode()` already handles uninitialized DI via fallback to `process.env['WORKRAIL_DEV']`.
+
+## Selected Approach
+
+Change `shouldShowStaleness`'s default parameter from `= DEV_STALENESS` to `= isDevMode()`. Remove the `DEV_STALENESS` const and its `process.env` read. Add `isDevMode` import.
+
+**Runner-up:** Pass `isDevMode()` explicitly at each of the 2 call sites. Lost because it's more verbose with no benefit.
+
+## Vertical Slices
+
+### Slice 1: Code change in `src/mcp/handlers/v2-workflow.ts`
+
+Files:
+- `src/mcp/handlers/v2-workflow.ts`
+
+Changes:
+1. Remove lines 46-49 (the `DEV_STALENESS` const and its JSDoc comment).
+2. Add `import { isDevMode } from '../dev-mode.js'` near the top (with other imports from `../`).
+3. Change `shouldShowStaleness` default parameter from `= DEV_STALENESS` to `= isDevMode()`.
+4. Update the JSDoc comment on `shouldShowStaleness` to remove the reference to `DEV_STALENESS` and explain that it now delegates to `isDevMode()`.
+
+### Slice 2: Update `devMode` flag description in `src/config/feature-flags.ts`
+
+Files:
+- `src/config/feature-flags.ts`
+
+Changes:
+1. Line 109: Replace the description to include staleness visibility:
+   ```
+   'Enable development features: staleness visibility for all workflow categories, structured tool-call timing on stderr, and /api/v2/perf/tool-calls endpoint'
+   ```
+
+### Slice 3: Update comments in `src/config/config-file.ts`
+
+Files:
+- `src/config/config-file.ts`
+
+Changes:
+1. Line 10 (module JSDoc): Remove `WORKRAIL_DEV_STALENESS` from the exclusion list.
+2. Lines 32-33 (ALLOWED_CONFIG_FILE_KEYS comment): Remove the bullet about `WORKRAIL_DEV_STALENESS`.
+
+### Slice 4: Update `AGENTS.md`
+
+Files:
+- `AGENTS.md`
+
+Changes:
+1. Line 141: Change `WORKRAIL_DEV_STALENESS=1` to `WORKRAIL_DEV=1` and update the description.
+
+### Slice 5: Update `docs/authoring-v2.md`
+
+Files:
+- `docs/authoring-v2.md`
+
+Changes:
+1. Line 495: Change `Set WORKRAIL_DEV_STALENESS=1` to `Set WORKRAIL_DEV=1`.
+
+### Slice 6: Update `docs/configuration.md`
+
+Files:
+- `docs/configuration.md`
+
+Changes:
+1. Line 44: Remove `WORKRAIL_DEV_STALENESS` from the excluded keys list.
+
+### Slice 7 (Optional): Update `docs/design/workrail-config-file-discovery.md`
+
+Files:
+- `docs/design/workrail-config-file-discovery.md`
+
+Changes:
+1. Lines 75, 147, 436: Update references from `WORKRAIL_DEV_STALENESS` to `WORKRAIL_DEV` or remove the separate entry.
+
+## Test Design
+
+- Run `npx vitest run` -- all existing tests should pass. No new tests needed; the logic in `shouldShowStaleness` is unchanged and the existing unit tests in `tests/unit/mcp/workflow-staleness.test.ts` cover it with explicit `devMode` parameters.
+- Run `npm run build` -- confirm TypeScript compiles cleanly after the import and default parameter changes.
+
+## Risk Register
+
+| Risk | Likelihood | Severity | Mitigation |
+|---|---|---|---|
+| DI container uninitialized when `isDevMode()` called | Very low | Low | `dev-mode.ts` fallback to `process.env['WORKRAIL_DEV']` |
+| Missing a doc location | Low | Cosmetic | All 6+1 locations identified and listed |
+| TypeScript import error | Low | Caught at build | `npm run build` verification |
+
+## PR Packaging Strategy
+
+Single PR: `feat(mcp): consolidate WORKRAIL_DEV_STALENESS into WORKRAIL_DEV`
+
+## Philosophy Alignment
+
+| Principle | Status | Why |
+|---|---|---|
+| DI for boundaries | Satisfied | `isDevMode()` uses DI-injected `IFeatureFlagProvider` |
+| Determinism | Satisfied | Flag is stable during a request |
+| YAGNI | Satisfied | No deprecated alias kept |
+| Document "why" | Satisfied | JSDoc and docs updated |
+| Immutability by default | Satisfied | `shouldShowStaleness` signature unchanged |
+
+## Plan Confidence
+
+- `unresolvedUnknownCount`: 0
+- `planConfidenceBand`: High
+- `estimatedPRCount`: 1
+- `followUpTickets`: None

package/docs/design/implementation-plan-walk-cache-depth-limit.md

@@ -0,0 +1,141 @@
+# Implementation Plan: Walk Cache, Depth Limit, Skip Dirs, Graceful Degradation
+
+## Problem Statement
+
+The `walkForRootedWorkflowDirectories` function has no depth limit and only skips `.git` and `node_modules`, making it vulnerable to very deep directory trees and slow on large repos. There is no caching, so every call to `createWorkflowReaderForRequest` does a fresh walk. `listRememberedRoots` throws on store failure, preventing callers from recovering. Both v2-workflow.ts handlers let `createWorkflowReaderForRequest` throws propagate uncaught, crashing handler responses.
+
+## Acceptance Criteria
+
+1. `shouldSkipDirectory` uses a `const SKIP_DIRS = new Set([...])` with 20 entries
+2. `walkForRootedWorkflowDirectories` takes a `depth` param (default 0), stops recursing at depth >= 5, logs to console.debug if `WORKRAIL_DEV=1`, and still discovers `.workrail` entries at exactly depth 5
+3. `discoverRootedWorkflowDirectories` has a module-level Map cache keyed on sorted resolved roots joined by `\0`, TTL 30s, exports `clearWalkCacheForTesting()`
+4. `createWorkflowReaderForRequest` wraps the discovery call in a 10s timeout; timeout errors are caught inside the function and return the graceful fallback with `managedStoreError` set
+5. `listRememberedRoots` returns `[]` on store failure (logs error, does not throw)
+6. `handleV2ListWorkflows` wraps `createWorkflowReaderForRequest` in try/catch returning `errNotRetryable('INTERNAL_ERROR', ...)`
+7. `handleV2InspectWorkflow` same fix
+8. Test: depth-5 found, depth-6 not found
+9. Test: cache hit (strict reference equality on second call)
+10. Test: skip list (build/ subdirectory not discovered)
+11. `npx vitest run` passes
+
+## Non-Goals
+
+- Cancelling the background walk after timeout
+- Making TTL configurable
+- Adding cache to `discoverWorkflowDirectoriesUnderRoot`
+- Changing the v2 execution engine or session handling
+
+## Philosophy-Driven Constraints
+
+- `SKIP_DIRS` must be a `const Set` (immutability by default)
+- `listRememberedRoots` must return `[]` on error (errors are data)
+- Comments must explain WHY: cache TTL tradeoff, non-cancelling timeout, why `[]` not throw
+- Try/catch in v2-workflow.ts must return structured `errNotRetryable` (errors are data)
+- No new abstractions beyond what is specified (YAGNI)
+
+## Invariants
+
+- A `.workrail` entry at depth 5 MUST be discoverable
+- Cache key uses `path.resolve` before building, then `sort().join('\0')`
+- The timeout error must NOT propagate out of `createWorkflowReaderForRequest`
+- `clearWalkCacheForTesting()` must be exported from `request-workflow-reader.ts`
+
+## Selected Approach
+
+Implement all 10 changes as specified. No runner-up. See design-candidates doc.
+
+**Critical implementation detail:** The depth guard must be placed INSIDE the loop in `walkForRootedWorkflowDirectories`, AFTER the `.workrail` check, BEFORE the recursive call:
+```typescript
+if (entry.name === '.workrail') { ... continue; }
+if (depth >= MAX_WALK_DEPTH) {
+  if (process.env.WORKRAIL_DEV === '1') console.debug('[workrail] walk depth limit reached at:', currentDirectory);
+  continue;
+}
+await walkForRootedWorkflowDirectories(entryPath, discoveredPaths, depth + 1);
+```
+
+## Vertical Slices
+
+### Slice 1: `request-workflow-reader.ts` structural changes
+- Replace `shouldSkipDirectory` with `SKIP_DIRS` Set
+- Add `MAX_WALK_DEPTH = 5` constant
+- Add `depth` param to `walkForRootedWorkflowDirectories`
+- Fix depth guard placement
+
+### Slice 2: `request-workflow-reader.ts` cache
+- Add module-level `walkCache: Map<string, { result: WorkflowRootDiscoveryResult; expiresAt: number }>`
+- Add cache key derivation and TTL check in `discoverRootedWorkflowDirectories`
+- Export `clearWalkCacheForTesting()`
+- Add cache comment
+
+### Slice 3: `request-workflow-reader.ts` timeout + listRememberedRoots fix
+- Import `withTimeout` from `./with-timeout.js`
+- Add `DISCOVERY_TIMEOUT_MS = 10_000`
+- Wrap `discoverRootedWorkflowDirectories` call in try/catch with timeout inside `createWorkflowReaderForRequest`
+- Fix `listRememberedRoots` to return `[]` on error
+
+### Slice 4: `v2-workflow.ts` handler fixes
+- Wrap `createWorkflowReaderForRequest` ternary in try/catch in `handleV2ListWorkflows`
+- Same for `handleV2InspectWorkflow`
+
+### Slice 5: Tests
+- Add depth boundary test (#8)
+- Add cache hit test (#9)
+- Add skip list test (#10)
+- Add `afterEach(() => clearWalkCacheForTesting())` to test suite
+
+## Test Design
+
+**Test 8 (depth boundary):**
+- Create temp dir with `.workrail/workflows` at depth 5 (5 levels deep from root)
+- Create temp dir with `.workrail/workflows` at depth 6 (6 levels deep from root)
+- Call `discoverRootedWorkflowDirectories([root])`
+- Assert depth-5 path is in `discovered`
+- Assert depth-6 path is NOT in `discovered`
+- Must call `clearWalkCacheForTesting()` in afterEach
+
+**Test 9 (cache hit):**
+- Create a unique temp dir with a `.workrail/workflows` entry
+- Call `discoverRootedWorkflowDirectories([root])` twice
+- Assert `result1 === result2` (strict reference equality)
+
+**Test 10 (skip list):**
+- Create temp dir with `.workrail/workflows` at root level (should be found)
+- Create `build/.workrail/workflows` inside the same root (should NOT be found)
+- Call `discoverRootedWorkflowDirectories([root])`
+- Assert root-level path is in `discovered`
+- Assert build/ path is NOT in `discovered`
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| Depth guard placed at wrong position | Low | Medium | Test #8 catches it |
+| Cache TTL check using wrong comparison | Low | Low | Test #9 catches stale results |
+| withTimeout import path wrong | Low | Low | TypeScript compile error will surface it |
+| try/catch wrapping too much of createWorkflowReaderForRequest | Low | Medium | Code review + test |
+
+## PR Packaging Strategy
+
+Single PR. All changes are in two source files and one test file. The changes are tightly coupled (cache + timeout must both be present; handler fixes are independent but small).
+
+## Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|---|---|---|
+| Slice 1: SKIP_DIRS Set | Immutability by default | Satisfied -- const Set |
+| Slice 1: depth limit | Validate at boundaries | Satisfied -- guard inside walk |
+| Slice 2: module-level Map cache | Immutability by default | Tension -- mutation confined, clearWalkCacheForTesting() export makes it explicit |
+| Slice 2: cache comment | Document why not what | Satisfied |
+| Slice 3: listRememberedRoots fix | Errors are data | Satisfied -- returns [] not throws |
+| Slice 3: timeout | Validate at boundaries | Satisfied -- at createWorkflowReaderForRequest boundary |
+| Slice 4: handler fixes | Errors are data | Satisfied -- errNotRetryable not throw |
+| Slice 5: tests | Prefer fakes over mocks | Satisfied -- real temp dirs |
+
+## Unresolved Unknowns
+
+`unresolvedUnknownCount`: 0
+
+## Plan Confidence Band
+
+High

package/docs/design/layer3b-ghost-nodes-design-candidates.md

@@ -0,0 +1,229 @@
+# Layer 3b Ghost Nodes -- Design Candidates
+
+*Investigative material. Not a final decision.*
+
+---
+
+## Problem Understanding
+
+### What Layer 3b Means
+
+The console's session detail view shows a DAG of workflow execution nodes via `RunLineageDag` (xyflow). Currently only nodes that were actually created appear in the DAG. Layer 3b adds "ghost nodes" for steps that were skipped due to `runCondition` evaluating to false at the top level:
+
+- Skipped nodes rendered at 0.25 opacity with a `[ SKIPPED ]` badge
+- Makes the DAG show the full workflow shape, not just the executed path
+- Helps users understand why a sparse DAG looks sparse (e.g. a small-task fast path jumped from phase 0 to phase 6)
+
+### Core Tensions
+
+1. **Labels vs simplicity**: Step labels (human-readable titles like "Phase 0: Triage and classify") are what make ghost nodes useful. But resolving them requires the compiled workflow, which is a backend I/O operation. Skipping labels is simpler but produces raw step IDs (`routine-context-gathering-depth`) that users can't parse.
+
+2. **Type safety vs ease**: Adding `isGhost: boolean` to `ConsoleDagNode` is one line but violates "make illegal states unrepresentable" -- ghost steps have no `hasRecap`, `hasFailedValidations`, `isTip`, `parentNodeId`, `createdAtEventIndex`, etc. A separate `ConsoleGhostStep` interface is correct but requires touching both mirrored type files.
+
+3. **Positioning accuracy vs scope**: Exact column positioning requires knowing the workflow's step index order, which the frontend doesn't have without an extra API call. Approximate positioning (sort by trace event index, which matches `nextTopLevel`'s evaluation order for top-level steps) is sufficient for MVP.
+
+4. **ReactFlow nodes vs overlays**: ReactFlow nodes participate in the layout graph (edges could connect to them). Absolute-positioned divs (like loop brackets) are simpler and sufficient since ghost nodes have no edges.
+
+### Existing Patterns
+
+Layer 3a (edge cause diamonds, loop brackets, CAUSE footer) set the pattern for this layer:
+- New data added as a field on `ConsoleDagRun` (`executionTraceSummary`)
+- Frontend extracts overlay positions in separate `useMemo` blocks in `RunLineageDag`
+- Overlay components rendered as absolute-positioned divs, NOT as ReactFlow nodes
+- Pure logic functions live in `session-detail-use-cases.ts`
+
+Relevant existing code:
+- `console/src/components/RunLineageDag.tsx` -- sub-features A/B/C as separate `useMemo` blocks
+- `console/src/views/session-detail-use-cases.ts` -- `groupTraceEntries`, `findEdgeCauseItem`, `getNodeRoutingItems`
+- `src/v2/usecases/console-service.ts` -- `projectSessionDetail`, `resolveStepLabels`, `extractStepTitlesFromCompiled`
+- `src/v2/durable-core/domain/decision-trace-builder.ts` -- `traceStepRunConditionSkipped` emits `evaluated_condition` + `step_id` ref + `SKIP:` summary
+
+### Where Skipped Steps Live
+
+`traceStepRunConditionSkipped()` is called in `workflow-interpreter.ts` `nextTopLevel()` for each top-level step whose `runCondition` returned false. This emits:
+```
+{ kind: 'evaluated_condition', summary: 'SKIP: taskComplexity (equals)', refs: [{kind: 'step_id', value: 'phase-2-deep-exploration'}] }
+```
+
+These appear in `run.executionTraceSummary.items`. The step IDs are recoverable from the frontend without backend changes. Labels are not.
+
+### What Makes This Hard
+
+- Ghost node labels require resolving a compiled workflow by hash -- the backend already does this for real node labels but via snapshot refs. Ghost steps need direct lookup by stepId from the compiled workflow.
+- Two mirrored type files (`console-types.ts` + `console/src/api/types.ts`) must be kept in sync manually.
+- Ghost nodes must be positioned within the ReactFlow canvas coordinate space -- they are siblings of real nodes in the same scrollable div.
+- The `evaluateCondition` trace items also appear for loop conditions (loop body entries) -- those must NOT become ghost nodes. Filter: only top-level step skips have `step_id` refs (not `loop_id` refs).
+
+---
+
+## Philosophy Constraints
+
+From `AGENTS.md` and `console/CLAUDE.md`:
+
+- **Make illegal states unrepresentable**: Ghost steps have fundamentally different shape from real nodes. Separate type required.
+- **Immutability by default**: All new interfaces must use `readonly` everywhere.
+- **Pure functions at use-case layer**: Ghost step extraction and positioning are pure functions in `session-detail-use-cases.ts`.
+- **Validate at boundaries**: Backend is the boundary for label resolution (I/O).
+- **YAGNI**: Don't add step-order-exact positioning if approximate is sufficient.
+- **Compose with small pure functions**: One function per concern -- extraction, positioning, rendering are separate.
+
+No philosophy conflicts found between stated rules and repo patterns.
+
+---
+
+## Impact Surface
+
+Adding `skippedSteps: readonly ConsoleGhostStep[]` to `ConsoleDagRun` is additive. Consumers:
+- `RunLineageDag.tsx` -- reads `run.skippedSteps` (new `useMemo` block)
+- `session-detail-use-cases.ts` -- positioning pure function
+- Backend `console-service.ts` -- populates the field
+- `console-types.ts` + `console/src/api/types.ts` -- both must be updated (manual mirror)
+- Existing test assertions on `ConsoleDagRun` shape -- `skippedSteps` is additive; old tests still pass
+
+The `buildLineageDagModel` signature does NOT need to change -- ghost positioning is a separate pure function consuming the layout model output.
+
+---
+
+## Candidates
+
+### Candidate A: Frontend-only ghost nodes (no labels)
+
+**Summary**: Extract skipped step IDs from `evaluated_condition` SKIP trace items on the frontend; render ghost nodes without step labels (show raw step ID).
+
+**Tensions resolved**: Zero backend changes. No mirrored type file sync needed.
+**Tensions accepted**: No step labels. Ghost nodes show raw IDs like `routine-context-gathering-depth`.
+
+**Boundary**: `session-detail-use-cases.ts` -- new pure function `getSkippedStepsFromTrace(items: readonly ConsoleExecutionTraceItem[]): readonly string[]` returning step IDs. `RunLineageDag.tsx` -- new sub-feature D `useMemo` computes ghost positions from active lineage model, renders absolute-positioned `GhostNodeOverlay` components.
+
+**Why this boundary**: Consistent with Layer 3a pattern. Pure function in use-case layer, rendering in view.
+
+**Failure mode**: Raw step IDs are unreadable to users. Feature ships but provides poor UX. Silent failure -- no error, just confusing UI.
+
+**Repo pattern**: Directly adapts Layer 3a overlay pattern. No new fields.
+
+**Gain**: Zero backend risk, minimal diff, fast to ship.
+**Give up**: Step labels (the primary user-facing value of the feature).
+
+**Scope**: Too narrow -- labels are 80% of the value.
+
+**Philosophy fit**: Honors YAGNI, small pure functions. Conflicts with "prefer explicit domain types" if ghost step is just `string`.
+
+---
+
+### Candidate B: Backend-emitted skippedSteps with labels (recommended)
+
+**Summary**: Add `skippedSteps: readonly ConsoleGhostStep[]` to `ConsoleDagRun`; backend populates it by scanning `executionTraceSummary.items` for SKIP entries and resolving titles from the already-loaded compiled workflow.
+
+**Tensions resolved**: Full step labels. Named `ConsoleGhostStep` interface. Follows exact Layer 3a precedent (`executionTraceSummary` was added the same way). Approximate positioning is sufficient.
+**Tensions accepted**: Two mirrored type files must sync. Backend `projectSessionDetail` grows slightly.
+
+**New types**:
+```typescript
+// In both console-types.ts and console/src/api/types.ts
+export interface ConsoleGhostStep {
+  readonly stepId: string;
+  readonly stepLabel: string | null;
+}
+// ConsoleDagRun gains:
+readonly skippedSteps: readonly ConsoleGhostStep[];
+```
+
+**Backend helper** in `console-service.ts`:
+```typescript
+function resolveSkippedSteps(
+  executionTrace: ConsoleExecutionTraceSummary | null,
+  workflowHash: string | null,
+  titlesByHash: Map<string, ReadonlyMap<string, string>>,
+): readonly ConsoleGhostStep[]
+```
+Filters `items` for `evaluated_condition` with `step_id` ref and `SKIP:` summary prefix; resolves labels from `titlesByHash` (already loaded by `resolveStepLabels`).
+
+**Frontend pure function** in `session-detail-use-cases.ts`:
+```typescript
+export function positionGhostNodes(
+  skippedSteps: readonly ConsoleGhostStep[],
+  model: LineageDagModel,
+): readonly PositionedGhostNode[]
+```
+Places ghost nodes at `depth = maxActiveDepth + 1`, evenly spaced in a dedicated ghost lane below the active lineage. `PositionedGhostNode` has `{ stepId, stepLabel, x, y }`.
+
+**Rendering in `RunLineageDag.tsx`**: New sub-feature D `useMemo` + `GhostNodeOverlay` absolute-positioned component. Not ReactFlow nodes. Not clickable (`pointerEvents: 'none'` on the node body, but tooltip on hover to show full step label).
+
+**Why this boundary**: `ConsoleGhostStep` as backend DTO matches how `executionTraceSummary` was added. Label resolution is I/O -- belongs at the backend boundary. Pure positioning function belongs in use-case layer.
+
+**Failure mode**: If `workflowHash` is null (no-workflow run), labels fall back to null, and ghost nodes show step ID. Same graceful degradation as real node labels.
+
+**Repo pattern**: Directly follows how Layer 3a added `executionTraceSummary` to `ConsoleDagRun`. Same file sequence, same pattern.
+
+**Gain**: Full step labels. Named type. Clean architecture. Graceful null fallback.
+**Give up**: Two type files must sync. Moderate backend diff.
+
+**Scope**: Best-fit. Satisfies acceptance criteria without extra API endpoints.
+
+**Philosophy fit**: Honors all principles. Explicit domain type, immutability, pure functions, validate at boundaries.
+
+---
+
+### Candidate C: ReactFlow custom node type with exact positioning
+
+**Summary**: Add ghost steps as `Node<GhostNodeData>[]` in the ReactFlow graph with `nodeType: 'ghost'`, positioned at the exact workflow-step-order column using the step's index in the compiled workflow fetched from a new frontend API call.
+
+**Tensions resolved**: Exact column positioning matching workflow step order. Ghost nodes as real ReactFlow nodes (future edge support). Hover/click behavior handled by ReactFlow.
+**Tensions accepted**: Extra API call creates loading race. New API endpoint needed. Custom `nodeTypes` map requires memoization in `RunLineageDag`.
+
+**Boundary**: New `useWorkflowStepsRepository` hook fetching `/api/v2/workflows/:hash/steps` (or reuse existing catalog endpoint). Session detail ViewModel joins session data + workflow steps. `buildLineageDagModel` extended to accept ghost steps with exact column indices.
+
+**Why this boundary**: Solves exact positioning by having the frontend know step order. But this is a new data dependency not currently in the session detail view's data model.
+
+**Failure mode**: If workflow steps API call fails, ghost nodes disappear entirely (non-graceful). Loading state race: ghost nodes flicker in when the secondary call resolves. `nodeTypes` must be defined outside render or in `useMemo` (easy to get wrong, causes ReactFlow remount warnings).
+
+**Repo pattern**: Departs significantly. No existing custom node types. No extra API calls in session detail view. Over-engineered for the goal.
+
+**Gain**: Exact positioning. Future edge support.
+**Give up**: Extra API call. Loading complexity. New endpoint needed. Significant scope expansion.
+
+**Scope**: Too broad. Not justified by acceptance criteria.
+
+**Philosophy fit**: Conflicts with YAGNI. Honors explicit types and exhaustiveness.
+
+---
+
+## Comparison and Recommendation
+
+| Criterion | A | B | C |
+|---|---|---|---|
+| Step labels | No | Yes | Yes |
+| Backend changes | None | Small additive | New endpoint |
+| Type safety | Weak | Strong | Strong |
+| Positioning | Approximate | Approximate | Exact |
+| Failure mode | Silent bad UX | Graceful null | Hard failure + flicker |
+| Repo pattern fit | Direct | Direct | Departs |
+| YAGNI | Over-honors | Balanced | Violates |
+
+**Recommendation: Candidate B.**
+
+Labels are not optional -- raw step IDs are meaningless to users. Candidate A saves 30 minutes and ships a feature that doesn't work. Candidate C solves an exact-positioning problem that the acceptance criteria don't require and introduces loading complexity.
+
+Candidate B follows the exact path Layer 3a established (`executionTraceSummary` was added as a backend-assembled field on `ConsoleDagRun`). The backend helper is small and reuses `extractStepTitlesFromCompiled` which already exists.
+
+---
+
+## Self-Critique
+
+**Strongest argument against B**: `projectSessionDetail` is already complex. Every new helper adds cognitive overhead and another I/O fan-out point. A determined advocate for A would argue: "Ship step IDs now, add labels in a follow-up when we have a codegen solution for the mirrored types."
+
+**Why A still loses**: The roadmap already says "requires backend to emit skipped step IDs" -- that's an acknowledgment that backend work is expected. The label resolution is 10 lines of code (reuses existing infra). The UX gap is not cosmetic.
+
+**What would justify C**: A product requirement saying ghost nodes must appear at their workflow-order column (not just after the active lineage). Evidence required: user feedback that approximate positioning is confusing. Not present.
+
+**Invalidating assumption**: If `traceStepRunConditionSkipped` is NOT actually called in the v2 engine (only in the v1 interpreter), then the trace items won't exist and ghost nodes won't appear for v2 sessions. `workflow-interpreter.ts` is the v1 interpreter. Need to verify whether the v2 engine emits equivalent traces. If not, this entire feature is a no-op for v2 sessions and the real work is adding trace emission to the v2 engine first.
+
+---
+
+## Open Questions for the Main Agent
+
+1. **V2 engine trace emission**: Does the v2 durable engine (`src/v2/`) emit `evaluated_condition` trace entries for top-level step `runCondition` evaluations? Or is this only in the v1 interpreter (`workflow-interpreter.ts`)? If v2 doesn't emit these, ghost nodes won't appear for any v2 sessions and the backend/frontend work is pointless without fixing the v2 engine first.
+
+2. **Ghost lane layout**: Should ghost nodes appear in a single horizontal band below the active lineage (all at the same Y, different X)? Or in a vertical column to the right of the active lineage (all at the same X, different Y)? The current layout is horizontal (depth = X axis, lane = Y axis) -- vertical stacking (same depth, different lanes) may be less intuitive.
+
+3. **Deduplication**: If a step is evaluated multiple times across multiple `continue_workflow` calls (e.g., re-entry in a session with multiple runs), the same `step_id` could appear in multiple SKIP trace items. Should ghost nodes be deduplicated by `stepId`? Answer: yes, show each skipped step only once.