@exaudeus/workrail 3.40.0 → 3.41.0

package/docs/ideas/design-candidates-session-tree-view.md

@@ -0,0 +1,196 @@
+# Design Candidates: Session Tree View in Console
+
+*Discovery session: 2026-04-18*
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Flat API vs tree UI**: `/api/v2/sessions` returns a flat array. The UI wants a tree grouped by parent-child relationships. Options: build tree client-side from parentSessionId index, or change the API. The existing repo pattern (flat projection DTOs, pure use-case functions) favors building the tree client-side.
+
+2. **Orphaned children vs tree integrity**: If a parent session is older than MAX_SESSIONS_TO_LOAD=500, its children have a dangling parentSessionId. Showing orphaned children as roots is the only safe fallback, but the tree is incomplete. Acceptable for MVP.
+
+3. **Filtering with tree structure**: When filtering by status or search, should the parent appear if only a child matches? Naive filtering breaks the tree. Better approach: include parent when any child matches. Adds complexity to filterSessions().
+
+4. **Type mirror sync**: ConsoleSessionSummary is duplicated between `src/v2/usecases/console-types.ts` (server) and `console/src/api/types.ts` (client mirror). Both must be updated in sync. This is an existing technical debt, not new -- adding parentSessionId just adds one more field to keep in sync.
+
+### Likely Seam
+
+The seam is between the flat sessions array and the tree render. The right place is a new pure function `buildSessionTree(sessions)` in `session-list-use-cases.ts`, not a new HTTP endpoint and not a modification to the GROUP_AXES grouping infrastructure.
+
+### What Makes This Hard
+
+The existing GROUP_AXES abstraction in `session-list-use-cases.ts` is flat -- each group has a string label. Tree grouping requires a fundamentally different rendering shape: a clickable coordinator SessionCard as the group header, with indented children below. Shoehorning tree rendering into GROUP_AXES produces an illegal state (coordinator appears as both a plain-text header label AND a card inside the group).
+
+The filter-with-tree interaction is the hardest sub-problem: when tree mode is active, a filter that excludes the parent but matches a child must still show the parent as context.
+
+---
+
+## Philosophy Constraints
+
+From CLAUDE.md and repo patterns:
+
+- **Immutability by default**: all new types use readonly fields
+- **Pure functions in use-cases**: business logic in `session-list-use-cases.ts`, not in React components
+- **Make illegal states unrepresentable**: coordinator session must not appear twice (as header AND as card)
+- **Errors are data**: orphaned children (parent not in loaded set) should degrade gracefully to root-level display, never throw
+- **YAGNI**: 2-level tree only for MVP; no recursive structure needed
+- **Compose with small pure functions**: `buildSessionTree()` should be pure and independently testable
+- **Validate at boundaries**: `extractParentSessionId()` happens in console-service.ts (the projection boundary); frontend trusts the value
+
+**No philosophy conflicts found.** CLAUDE.md principles and repo patterns are consistent for this problem.
+
+---
+
+## Impact Surface
+
+If `ConsoleSessionSummary` gains a `parentSessionId` field:
+- `src/v2/usecases/console-types.ts` -- server type definition
+- `console/src/api/types.ts` -- client type mirror (must stay in sync manually)
+- `projectSessionSummary()` in `console-service.ts` -- new field returned in the projection
+- `filterSessions()` in `session-list-use-cases.ts` -- needs parentIndex for tree-mode filtering
+- `SessionList.tsx` -- new tree rendering path
+- Any future codegen for the type mirror would pick this up automatically
+
+Existing consumers of the flat `/api/v2/sessions` endpoint are unaffected -- the new field is additive and optional for root sessions.
+
+---
+
+## Candidates
+
+### Candidate A -- Minimal: add parentSessionId, reuse GROUP_AXES with a 'tree' option
+
+**Summary:** Add `parentSessionId` to both type files. Add a 'tree' option to GROUP_AXES that groups children under their parent's sessionId as the group key. The existing SessionGroup component shows the parent sessionId as the group label; children are SessionCards inside.
+
+**Tensions resolved:** API stability (flat array unchanged). Type sync (one field added to both).
+
+**Tensions accepted:** GROUP_AXES abstraction is abused. SessionGroup renders a plain-text label (the parent sessionId string), not a clickable coordinator SessionCard.
+
+**Boundary solved at:** Frontend GROUP_AXES layer only.
+
+**Why that boundary:** Minimum viable change -- no new components, no new functions.
+
+**Failure mode:** Coordinator session appears BOTH as the group label text AND as a SessionCard inside the group (it's in the flat list). The group header is a non-navigable string, not a card. This is an illegal state: the coordinator is visible twice in different forms. Fixing this requires adding a custom node-renderer to SessionGroup -- at which point you've rebuilt Candidate B anyway.
+
+**Repo pattern:** Abuses GROUP_AXES -- designed for grouping by string key, not parent-child hierarchies.
+
+**Gains:** Zero new components. Minimal diff.
+
+**Losses:** Visual quality. Coordinator not navigable from group header. No tree connector lines. Duplication bug.
+
+**Scope:** Too narrow -- doesn't deliver the tree view quality described in the backlog.
+
+**Philosophy:** YAGNI honored. Make illegal states unrepresentable violated (coordinator appears twice).
+
+---
+
+### Candidate B -- Best-fit: new buildSessionTree() + dedicated SessionTreeView component
+
+**Summary:** Add `parentSessionId: string | null` to `ConsoleSessionSummary` on server and client. Implement `extractParentSessionId(events)` in `console-service.ts` (O(1), session_created is always eventIndex=0). Add a new pure function to `session-list-use-cases.ts`:
+
+```typescript
+interface SessionTreeNode {
+  readonly session: ConsoleSessionSummary;
+  readonly children: readonly ConsoleSessionSummary[];
+}
+
+interface SessionTree {
+  readonly roots: readonly SessionTreeNode[];
+  readonly orphanChildIds: ReadonlySet<string>;
+}
+
+function buildSessionTree(sessions: readonly ConsoleSessionSummary[]): SessionTree
+```
+
+Add a view mode toggle (tree/flat) to `SessionListState`. When tree mode is active, render a new `SessionTreeView` component: coordinator cards at root level, children indented 20px with a CSS `border-left` connector line on the wrapper div. Orphans (parent not loaded) appear as roots.
+
+Modify `filterSessions()` to accept an optional `parentIndex: ReadonlyMap<string, string>` parameter. When tree mode is active: if a child matches the filter, include its parent too (parent appears even if it doesn't match the filter text/status).
+
+**Tensions resolved:** API stability. Tree rendering quality (no duplication). Orphan handling (explicit orphanChildIds set). Filter+tree interaction (parent included when child matches).
+
+**Tensions accepted:** Type mirror sync remains manual.
+
+**Boundary solved at:** Frontend use-cases layer (`buildSessionTree()` is pure) + new presenter component.
+
+**Why that boundary:** `buildSessionTree()` is pure and testable without React. The tree is computed once per render cycle, not per-card. Follows the exact same pattern as the existing pure functions in `session-list-use-cases.ts`.
+
+**Failure mode:** Filter-with-tree is the hardest case. The `filterSessions()` modification adds complexity. If the logic is wrong, the parent could be shown when it shouldn't (e.g., filter=complete, parent is in_progress, child is complete -- should the in_progress parent appear?). Decision: include parent when any child matches, regardless of parent's own status. This is the most useful behavior for the tree view use case.
+
+**Repo pattern:** Follows the pure use-cases + presenter pattern exactly. New SessionTreeView component follows the same presenter shape as existing components.
+
+**Gains:** Clean tree rendering with visual connectors. Navigable coordinator cards. No duplication. Pure testable logic. Degrades gracefully for orphaned children.
+
+**Losses:** Slightly more code than Candidate A. Two components for the same view (flat list + tree view).
+
+**Scope:** Best-fit -- delivers the design described in the backlog without overbuilding.
+
+**Philosophy:** All principles honored. Immutability, explicit domain types, pure functions, YAGNI (2-level tree only).
+
+---
+
+### Candidate C -- Server-side tree: new `GET /api/v2/sessions/tree` endpoint
+
+**Summary:** Add a new server endpoint that returns `{ roots: ConsoleSessionSummaryWithChildren[], orphans: ConsoleSessionSummary[] }`. The flat `/api/v2/sessions` endpoint is unchanged. Server builds the tree from the loaded session set, embedding children under their parent in the response.
+
+**Tensions resolved:** Tree structure computed at the source of truth (server, with access to the full 500-session window). Client receives a ready-to-render tree.
+
+**Tensions accepted:** New endpoint means new React Query hook, new cache key, new loading state. Two overlapping endpoints that must be kept consistent.
+
+**Boundary solved at:** Server projection layer (`console-service.ts`).
+
+**Why that boundary:** Server has the full session set in scope; client doesn't need to rebuild the tree from a flat list.
+
+**Failure mode:** API surface grows. The flat endpoint and tree endpoint must stay consistent. Cache invalidation logic must be updated for both. If the tree endpoint is slow (500 sessions), the flat endpoint is still fast -- users may not understand why.
+
+**Repo pattern:** Departs from the existing pattern (all console endpoints return flat projection DTOs). Adds server complexity for a problem that client-side pure functions can solve with zero HTTP overhead.
+
+**Gains:** Tree is always consistent (parent and children computed together). Client rendering is simpler -- just map the tree response.
+
+**Losses:** API surface growth. Additional React Query hook. More complex cache invalidation. Server-side complexity for a problem solvable client-side.
+
+**Scope:** Too broad -- the flat list already contains all the data needed to build the tree client-side.
+
+**Philosophy:** Conflicts with YAGNI (new endpoint not needed). Conflicts with validate-at-boundaries (boundary moved to server when client can handle it).
+
+---
+
+## Comparison and Recommendation
+
+| Tension | A | B | C |
+|---|---|---|---|
+| API stability | Resolves | Resolves | Adds new endpoint |
+| Tree rendering quality | Fails (duplication) | Resolves | Resolves |
+| Orphan handling | None | Explicit | Server-side |
+| Filter+tree interaction | Broken | Manageable | Handled server-side |
+| Repo pattern fit | Abuses GROUP_AXES | Follows pure-function pattern | Departs from flat-DTO pattern |
+| Reversibility | Easy | Easy | Medium |
+| Philosophy fit | Partial | Full | Partial |
+
+**Recommendation: Candidate B.**
+
+B resolves all real tensions without overbuilding. It follows the existing pure-function/presenter split the repo already practices. `buildSessionTree()` is pure and testable independently of React. The filter-with-tree interaction is manageable with a contained change to `filterSessions()`. The 2-level tree constraint matches the backlog's examples exactly.
+
+---
+
+## Self-Critique
+
+**Strongest argument against B:** What if the Phase 2 UX design requires 3-level trees (coordinator → child coordinator → grandchild)? B explicitly excludes this by using `readonly children: readonly ConsoleSessionSummary[]` instead of `readonly children: readonly SessionTreeNode[]`. Changing to recursive SessionTreeNode later is a contained change, but it would require updating the SessionTreeView component too.
+
+**Pivot conditions:**
+- If Phase 2 UX requires >2 levels: change `SessionTreeNode.children` to `readonly SessionTreeNode[]` and make `SessionTreeView` recursive. The `buildSessionTree()` function would need to become recursive as well.
+- If filter+tree interaction proves too complex: ship tree view without filter support in tree mode, show a "tree view disabled while filtered" state.
+- If the type mirror sync problem grows: introduce codegen for the type mirror (separate from this feature).
+
+**Assumption that would invalidate B:** If the flat `/api/v2/sessions` endpoint doesn't return all sessions needed to build a complete tree (e.g., if sessions are paginated server-side before reaching the client). Currently MAX_SESSIONS_TO_LOAD=500 applies before the response; if a coordinator and its children are all within the 500-session window, the tree will be complete. If the coordinator is old but children are recent, the tree will be incomplete -- but this degrades gracefully (children show as roots).
+
+---
+
+## Open Questions for the Main Agent
+
+1. **Filter behavior in tree mode**: When filtering by status=in_progress and the coordinator is complete but has an in_progress child -- should the coordinator appear? Proposed: yes, include parent when any child matches. Is this the right UX?
+
+2. **Tree mode default or opt-in**: Should the tree view be the default mode, or should users opt in via a toggle? Given that zero sessions have parentSessionId today, defaulting to tree view would show an identical flat list -- tree mode only activates when coordinator sessions exist.
+
+3. **Connector line style**: Simple `border-left` CSS on the indented container, or tree-line SVG connectors like `TreeLine.tsx` (which already exists in `console/src/components/TreeLine.tsx`)? The existing component should be used if it fits.

package/docs/ideas/design-review-findings-console-session-tree-impl.md

@@ -0,0 +1,75 @@
+# Design Review Findings: Console Session Tree Implementation (Phase 3)
+
+*2026-04-18 -- Covering Slice 5: SessionTreeView component*
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Acceptable? | Condition for Failure | Notes |
+|---|---|---|---|
+| Transient expand state (resets on navigation) | Yes | Never -- no acceptance criterion requires persistence | Acceptable for MVP |
+| Auto-expand only on initial render | Yes | User expects newly-in_progress coordinators to auto-expand during the page session | Known limitation, acceptable |
+| Expand toggle outside ConsoleCard | Yes | Layout mismatch -- toggle disconnected from card visually | WorkspaceView.tsx proves the flex-row pattern works |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Handled? | Mitigation | Risk |
+|---|---|---|---|
+| Expand toggle triggers card navigation | Yes | Toggle is separate DOM button outside ConsoleCard | None |
+| Coordinator with no children shows toggle | Yes | Hide toggle when children.length === 0 | None |
+| cycle in parentSessionId | Yes | buildSessionTree() cycle guard | None |
+| Newly in_progress coordinator won't auto-expand after initial render | Partial | Accepted for MVP; useState init only covers initial render | Low |
+| TypeScript type errors | None expected | All types already defined in Slices 1-4 | None |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Simpler variant adopted:** Skip auto-expand entirely, or keep auto-expand for initial render only. Decision: keep auto-expand on initial render (simple useState initializer), accept that mid-session state changes won't auto-expand. Avoids useEffect/useMemo complexity.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Status |
+|---|---|
+| Pure functions in use-cases | Satisfied -- buildSessionTree() is pure |
+| Immutability | Satisfied -- readonly types throughout |
+| Compose with small functions | Satisfied -- SessionTreeView is a named function |
+| YAGNI | Satisfied -- auto-expand is minimal |
+| Functional/declarative | Acceptable tension -- useState Map is mutable but correct for React UI state |
+
+---
+
+## Findings
+
+### Red (must fix before implementation)
+
+None.
+
+### Orange (should address)
+
+**O1: Expand toggle placement requires specific layout**
+The expand toggle must be in a flex row with the coordinator card, but the coordinator card itself must not be a parent of the toggle (avoids nested interactive elements). The pattern from WorkspaceView.tsx is `<div className="flex items-start gap-2">` containing `[toggle button]` then `[coordinator card button]`.
+
+### Yellow (advisory)
+
+**Y1: Auto-expand fires only on initial render**
+If a coordinator transitions to in_progress after the component first renders, it will not auto-expand. This is acceptable for MVP.
+
+---
+
+## Recommended Revisions
+
+1. Use `flex items-start gap-2` wrapper row for [expand-toggle, coordinator-card] to avoid nested interactive elements.
+2. Initialize expand state with `useState(() => new Map(roots.filter(...).map(n => [n.session.sessionId, true])))` -- function initializer to avoid re-running on re-renders.
+
+---
+
+## Residual Concerns
+
+- Visual quality of the amber left border + [COORD] badge combination requires human visual review -- cannot be verified by TypeScript check.
+- No real coordinator sessions exist locally, so end-to-end visual testing requires either manual mock data or running a spawn_agent workflow.

package/docs/ideas/design-review-findings-session-tree-view.md

@@ -0,0 +1,88 @@
+# Design Review Findings: Session Tree View in Console
+
+*Discovery session: 2026-04-18*
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Violates Acceptance Criteria? | Conditions for Failure | Verdict |
+|---|---|---|---|
+| Manual type mirror sync | No -- TypeScript catches at build time | Developer forgets to update client mirror | Acceptable -- compiler enforces |
+| Incomplete tree when parent outside 500-session window | No -- degrades to orphan-as-root | Coordinator runs many children over days | Acceptable for MVP |
+| 2-level tree max | No -- engine depth limit aligns (maxSubagentDepth=2) | If maxSubagentDepth raised in config | Acceptable -- contained change to fix |
+| Tree mode opt-in (not default) | No -- flat view is current default | Users never discover toggle | Acceptable -- can add auto-suggest later |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Handled? | Missing Mitigation | Risk |
+|---|---|---|---|
+| Cyclic parentSessionId (self-parent) | Partial | Explicit cycle guard in buildSessionTree(): `if (parentId === session.sessionId) treat as root` | Low -- easy to add, must add |
+| Orphaned child (parent outside window) | Yes | Optional: 'child session' badge. Low priority. | Low |
+| Filter shows no results in tree mode | Yes -- existing empty-state UI handles it | None needed | Low |
+| Tree toggle state lost on navigation | Not handled | Persist in sessionStorage or URL param. Low priority. | Low |
+| Client mirror type not updated | Yes -- TypeScript build fails | None needed | None at runtime |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Runner-up (C, server-side tree):** No elements worth borrowing. Client already has all 500 sessions; server-side computation adds API surface with no benefit.
+
+**Simpler variant adopted:** Tree mode and filter mode are mutually exclusive for MVP. When tree mode is active, status/search filters are disabled (or auto-cleared). This eliminates the filter+tree parentIdIndex complexity from filterSessions() entirely. The more complex filter-aware tree can be added later when coordinator sessions are common enough to justify it.
+
+---
+
+## Philosophy Alignment
+
+**Satisfied:** Immutability, make illegal states unrepresentable, compose with small pure functions, validate at boundaries, errors as data, YAGNI.
+
+**Under tension (acceptable):**
+- Functional/declarative: buildSessionTree() is imperative-style but pure. Same-input/same-output invariant holds.
+- Type mirror sync: two copies of ConsoleSessionSummary can diverge, but TypeScript build catches this before runtime.
+
+**No risky philosophy tensions.**
+
+---
+
+## Findings
+
+### Red (must fix before implementation)
+
+None.
+
+### Orange (should fix before implementation)
+
+**O1: Cycle guard missing in design**
+buildSessionTree() must guard against `parentSessionId === session.sessionId`. Without this, a session appears both as a root and as its own child. Add explicitly to implementation.
+
+### Yellow (low priority, note for future)
+
+**Y1: Orphaned child has no visual indicator**
+Children with a dangling parentSessionId (parent outside 500-session window) show as roots with no indication they're children. A small 'child session' badge would improve UX for multi-day coordinator runs. Not needed for MVP.
+
+**Y2: Tree toggle state not persisted**
+Navigating to session detail and back resets tree/flat mode. Could be persisted in sessionStorage or URL param. Not needed for MVP.
+
+**Y3: Tree mode not auto-suggested when coordinator sessions exist**
+Users may not discover the tree mode toggle. When any session has `parentSessionId != null`, show a subtle prompt or auto-activate tree mode. Not needed for MVP.
+
+---
+
+## Recommended Revisions
+
+1. **Add cycle guard to buildSessionTree():** Before adding a session to a parent's children array, check `parentSessionId !== session.sessionId`. Treat self-parenting sessions as roots.
+
+2. **Make filter mode and tree mode mutually exclusive:** When tree mode is activated, clear active filters (or disable the filter controls). When a filter is applied, tree mode is disabled. Show a clear UI state for this (e.g., "Filters disabled in tree view").
+
+3. **Document 2-level max as explicit constant:** Define `TREE_MAX_DEPTH = 2` in session-list-use-cases.ts with a comment explaining the engine's maxSubagentDepth alignment.
+
+---
+
+## Residual Concerns
+
+1. **Untestable in real UI until coordinator sessions are run.** Zero sessions have parentSessionId today. The implementation can be verified only via manual testing with artificially constructed session data or by running an actual spawn_agent workflow. Recommendation: add a simple unit test for buildSessionTree() with mock ConsoleSessionSummary objects in session-list-use-cases.test.ts (if the test file exists -- check before implementing).
+
+2. **Filter+tree interaction deferred, not designed.** The current design explicitly excludes filtering while in tree mode. If a future sprint adds filter+tree, the parentIdIndex approach was analyzed and is the right path -- but it must be designed and tested carefully to avoid surprising UX (parent shown in 'complete' filter even though it's in_progress).

package/docs/ideas/implementation_plan_session_tree_view.md

@@ -0,0 +1,238 @@
+# Implementation Plan: Session Tree View in Console
+
+*Created: 2026-04-18*
+
+---
+
+## Problem Statement
+
+WorkRail creates a separate session for every workflow run. When spawn_agent is used, a coordinator session creates multiple child sessions. Today, all sessions appear as a flat list in the console -- there is no visual grouping that shows coordinator-child relationships. The `parentSessionId` field exists in the `session_created` event schema and is written by `makeSpawnAgentTool`, but it is not surfaced in `ConsoleSessionSummary` or rendered in the console UI.
+
+---
+
+## Acceptance Criteria
+
+1. `ConsoleSessionSummary` includes a `parentSessionId: string | null` field. Root sessions have `null`; child sessions have the parent's session ID.
+2. `/api/v2/sessions` response includes `parentSessionId` on each session summary.
+3. The console SessionList includes a tree view mode toggle.
+4. When tree view is active: coordinator sessions (sessions that have children) display their child sessions indented below them, separated by a `TreeLine` connector.
+5. When tree view is active: filter controls are disabled with a clear UI indicator.
+6. When tree view is active: sessions with no children display identically to the flat view.
+7. Orphaned children (parent session not in the loaded 500-session set) display as root sessions in tree view.
+8. `buildSessionTree()` handles the case where `parentSessionId === sessionId` (self-parent) by treating the session as a root.
+9. TypeScript build passes with no new errors.
+
+---
+
+## Non-Goals
+
+- No new HTTP endpoints (flat `/api/v2/sessions` is unchanged except for the new field).
+- No multi-level (depth > 2) tree rendering for MVP.
+- No filter+tree interaction for MVP (tree mode and filter mode are mutually exclusive).
+- No pagination changes.
+- No persistence of tree view toggle state.
+- No automatic activation of tree mode.
+
+---
+
+## Philosophy-Driven Constraints
+
+- **Immutability by default**: all new interfaces use `readonly`.
+- **Pure functions in use-cases**: `buildSessionTree()` is a pure function with no side effects, in `session-list-use-cases.ts`. No business logic in React components.
+- **Make illegal states unrepresentable**: coordinator session appears exactly once (as a root card). Cycle guard prevents self-parenting.
+- **Explicit domain types**: `SessionTree` and `SessionTreeNode` are named interfaces, not anonymous objects.
+- **YAGNI**: 2-level tree, mutually exclusive filter/tree modes, no new endpoints.
+- **Errors as data**: `buildSessionTree()` returns an `orphanChildIds` set; never throws on missing parents.
+
+---
+
+## Invariants
+
+1. `parentSessionId` is `null` for root sessions, a non-empty string for child sessions.
+2. `buildSessionTree()` is a pure function: same input always produces the same output.
+3. A session with `parentSessionId === sessionId` is treated as a root (cycle guard).
+4. An orphaned child (parent not in the input sessions array) is included in `orphanChildIds` and rendered as a root.
+5. The flat `/api/v2/sessions` endpoint response is backward-compatible: `parentSessionId` is a new additive field.
+6. `console/src/api/types.ts` mirrors `src/v2/usecases/console-types.ts` for `ConsoleSessionSummary` -- both must be updated together.
+
+---
+
+## Selected Approach
+
+**Candidate B: `buildSessionTree()` pure function + `SessionTreeView` presenter**
+
+See `design-candidates-session-tree-view.md` for full analysis. Summary: add `parentSessionId` to the type chain (server + client mirror), extract it at the projection boundary in `console-service.ts`, build the tree client-side in a pure function, and render it in a new presenter component using the existing `TreeLine` connector component.
+
+**Runner-up:** Candidate C (server-side tree endpoint) -- loses because the flat list already contains all data needed; a new endpoint adds API surface with no benefit.
+
+---
+
+## Vertical Slices
+
+### Slice 1: Add `parentSessionId` to server-side types and projection
+
+**Files changed:**
+- `src/v2/usecases/console-types.ts` -- add `readonly parentSessionId: string | null` to `ConsoleSessionSummary`
+- `src/v2/usecases/console-service.ts` -- add `extractParentSessionId(events)` function, include field in `projectSessionSummary()` return value
+
+**Acceptance criterion:** `GET /api/v2/sessions` response includes `parentSessionId: null` on all existing sessions. TypeScript build passes.
+
+**Pattern to follow:** `extractGitBranch(events)` / `extractRepoRoot(events)` in `console-service.ts` -- scan events for `session_created`, return `data.parentSessionId ?? null`.
+
+**Risk:** Low. Additive field, backward-compatible.
+
+---
+
+### Slice 2: Update client-side type mirror
+
+**Files changed:**
+- `console/src/api/types.ts` -- add `readonly parentSessionId: string | null` to `ConsoleSessionSummary`
+
+**Acceptance criterion:** TypeScript build of the console package passes. The new field is accessible in all React components that receive `ConsoleSessionSummary`.
+
+**Risk:** None. Compile-time only.
+
+---
+
+### Slice 3: Add `buildSessionTree()` to session-list-use-cases
+
+**Files changed:**
+- `console/src/views/session-list-use-cases.ts` -- add `SessionTreeNode`, `SessionTree` interfaces and `buildSessionTree()` function
+
+**Implementation:**
+```typescript
+export interface SessionTreeNode {
+  readonly session: ConsoleSessionSummary;
+  readonly children: readonly ConsoleSessionSummary[];
+}
+
+export interface SessionTree {
+  readonly roots: readonly SessionTreeNode[];
+  readonly orphanChildIds: ReadonlySet<string>;
+}
+
+export const TREE_MAX_DEPTH = 2; // aligns with engine's default maxSubagentDepth
+
+export function buildSessionTree(sessions: readonly ConsoleSessionSummary[]): SessionTree {
+  // Build parent -> children index
+  // Cycle guard: skip if parentSessionId === sessionId
+  // Orphan detection: if parent not in session set, add to orphanChildIds
+  // Return roots (sessions with no parent, plus orphaned children as roots) with children attached
+}
+```
+
+**Acceptance criterion:** Unit test in `console/src/views/session-list-use-cases.test.ts` (create if not exists) covers: empty input, all roots, parent-child pairs, cycle detection, orphaned children.
+
+**Risk:** Low. Pure function, no I/O.
+
+---
+
+### Slice 4: Add tree view mode to SessionList state and reducer
+
+**Files changed:**
+- `console/src/views/session-list-reducer.ts` -- add `viewMode: 'flat' | 'tree'` to state; add `view_mode_changed` action; when `view_mode_changed` to `tree`, clear filters
+- `console/src/hooks/useSessionListViewModel.ts` (or equivalent) -- expose `viewMode` and `dispatch` for tree toggle
+
+**Acceptance criterion:** Toggling to tree mode clears active status filter and search. State transitions are deterministic. TypeScript build passes.
+
+**Risk:** Low. Reducer is pure, state change is straightforward.
+
+---
+
+### Slice 5: Add `SessionTreeView` component and tree toggle UI
+
+**Files changed:**
+- `console/src/views/SessionList.tsx` -- add tree/flat mode toggle button; when `viewMode === 'tree'`, render `SessionTreeView` instead of the flat list; show "Filters disabled in tree view" when tree mode active and filters would normally show
+- New component `SessionTreeView` (inline in `SessionList.tsx` or in a new file) -- renders `SessionTreeNode[]` with `TreeLine` wrappers for indented children
+
+**Acceptance criterion:**
+- Toggle button visible in toolbar
+- Clicking toggle switches between tree and flat mode
+- In tree mode: coordinator sessions show children indented below using `TreeLine`
+- In tree mode: filter controls show a disabled state or a note
+- In tree mode with no coordinator sessions: renders identically to flat mode (no indentation)
+- `TreeLine` amber connector lines appear between coordinator card and child cards
+
+**Risk:** Medium. No real coordinator sessions exist for manual testing. Must use mock data or construct a test scenario.
+
+---
+
+## Test Design
+
+### Unit tests (`console/src/views/session-list-use-cases.test.ts`)
+
+Add a new `describe('buildSessionTree')` block:
+1. Empty input -> `{ roots: [], orphanChildIds: Set() }`
+2. All root sessions (no parentSessionId) -> all in roots, no orphans
+3. One coordinator with two children -> coordinator root with two children attached
+4. Orphaned child (parent not in input) -> child in roots, parentId in orphanChildIds
+5. Cycle detection (parentSessionId === sessionId) -> treated as root
+6. Multiple coordinators with overlapping children (edge case -- shouldn't occur but test graceful handling)
+
+### Build verification
+
+- `npm run build` (or equivalent) in both workrail root and console package must pass with no new TypeScript errors.
+
+### Manual verification
+
+- Create a test session data fixture (mock two sessions with parent-child relationship) and verify tree rendering visually.
+- Or: run a `spawn_agent` workflow in the daemon and observe the console.
+
+---
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| Cycle in parentSessionId causes infinite loop | Low | High | Cycle guard in buildSessionTree() (Slice 3) |
+| Client mirror not updated with server type | Low | Low | TypeScript build fails immediately |
+| No real coordinator sessions to test against | High | Medium | Unit tests cover the logic; manual test with mock data |
+| Phase 2 UX design requires depth-3 trees | Low | Medium | Change `children: readonly ConsoleSessionSummary[]` to `readonly SessionTreeNode[]`; contained change |
+| Tree mode breaks existing GROUP_AXES grouping | None | N/A | Tree mode is a separate view mode; GROUP_AXES unchanged |
+
+---
+
+## PR Packaging Strategy
+
+**Single PR: `feat/console-session-tree`**
+
+All 5 slices in one PR. Rationale:
+- Slices 1-2 (type changes) are tiny and safe but useless without the rendering
+- Slices 3-4 (logic) are testable independently but nothing to show
+- Slice 5 (UI) depends on all prior slices
+- The entire change is low-risk and additive -- no breaking changes
+- A single PR is easier to review as a coherent feature
+
+---
+
+## Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|---|---|---|
+| 1 (server type + extraction) | Validate at boundaries | Satisfied -- extraction at service boundary |
+| 1 | Compose with small pure functions | Satisfied -- extractParentSessionId follows extractRepoRoot pattern |
+| 1 | Immutability | Satisfied -- readonly field |
+| 2 (client mirror) | Make illegal states unrepresentable | Tension -- manual sync; TypeScript catches divergence at build time |
+| 3 (buildSessionTree) | Pure function composition | Satisfied |
+| 3 | Errors as data | Satisfied -- orphanChildIds, no throws |
+| 3 | Make illegal states unrepresentable | Satisfied -- cycle guard prevents self-parenting |
+| 4 (reducer) | Determinism over cleverness | Satisfied -- pure reducer |
+| 4 | Functional/declarative | Satisfied |
+| 5 (UI) | Compose with small pure functions | Satisfied -- SessionTreeView is a pure presenter |
+| 5 | YAGNI | Satisfied -- 2-level only, no filter+tree |
+
+---
+
+## Follow-Up Tickets
+
+- **Visual indicator on orphaned child sessions** (Y1): Add a small 'child session' badge to sessions in `orphanChildIds`. Low priority.
+- **Persist tree toggle state** (Y2): Save to sessionStorage or URL param. Low priority.
+- **Auto-suggest tree mode when coordinator sessions exist** (Y3): Detect `parentSessionId != null` in session list; show a subtle prompt. Low priority.
+- **Filter+tree interaction** (design exists): Add `parentIdIndex` to `filterSessions()` so tree mode and filter mode are compatible. Design is documented in `design-candidates-session-tree-view.md`.
+
+---
+
+## Plan Confidence
+
+- `unresolvedUnknownCount`: 1 (no real coordinator sessions to validate tree rendering end-to-end -- mitigated by unit tests)
+- `planConfidenceBand`: High

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/workrail",
-  "version": "3.40.0",
+  "version": "3.41.0",
   "description": "Step-by-step workflow enforcement for AI agents via MCP",
   "license": "MIT",
   "repository": {
@@ -103,6 +103,7 @@
     "open": "^11.0.0",
     "reflect-metadata": "^0.2.0",
     "semver": "^7.7.2",
+    "tinyglobby": "^0.2.15",
     "tsconfig-paths": "^4.2.0",
     "tslib": "^2.8.1",
     "tsyringe": "^4.8.0",