@exaudeus/workrail 3.40.0 → 3.42.0

package/docs/design/context-assembly-design-candidates.md

@@ -0,0 +1,199 @@
+# Design Candidates: Context Assembly Layer v1
+
+*Generated during coding-task-workflow-agentic session | 2026-04-19*
+
+---
+
+## Problem Understanding
+
+### Core Tensions
+
+1. **Clean DI vs. pragmatic inline construction**: `LocalSessionSummaryProviderV2` is
+   wired through the full DI container in the MCP server process. The coordinator runs
+   as a CLI in a separate process. We cannot share the DI container. The coordinator
+   composition root (`src/cli-worktrain.ts`) must construct the provider inline.
+
+2. **Neverthrow ResultAsync vs. custom Result**: Storage layer uses neverthrow. New
+   `src/context-assembly/` uses the repo's custom `Result<T,E>` (`kind: 'ok'|'err'`).
+   The bridge must happen at the `infra.ts` boundary.
+
+3. **Partial failure semantics**: Each source (gitDiff, priorNotes) must fail
+   independently without aborting context assembly. `Promise.all()` is safe because
+   each source always resolves to a `Result` (never throws) when implemented correctly.
+
+4. **Backward compatibility vs. interface evolution**: Adding `contextAssembler?` as
+   optional to `CoordinatorDeps` and optional 4th arg to `spawnSession` keeps all
+   existing tests and callers working without modification.
+
+### Likely Seam
+
+The real seam is `CoordinatorDeps.spawnSession`. The coordinator calls this to dispatch
+a session. Context bundle assembly belongs immediately before this call.
+
+### What Makes This Hard
+
+- `LocalSessionEventLogStoreV2` requires `FileSystemPortV2` (a composite of 5 sub-ports
+  including write/fd ops). But `load()` only calls `readFileUtf8`. All write methods
+  can be stubs for read-only use, but this is a partial lie against the interface contract.
+- `LocalDirectoryListingV2` takes `DirectoryListingOpsPortV2` (separate, simpler) --
+  NOT the full `FileSystemPortV2`. These are separate ports.
+- Two Result type systems (neverthrow vs custom) must coexist without leaking across
+  the `infra.ts` boundary.
+- `Sha256PortV2` is injected into `LocalSessionEventLogStoreV2` but only called in
+  `append()`, not `load()`. Safe to stub.
+
+---
+
+## Philosophy Constraints
+
+From `CLAUDE.md` (system-wide agent instructions):
+
+- **Errors are data**: Use `Result<T,E>` values. No throwing for expected failures.
+- **DI for boundaries**: Inject I/O effects; keep core logic testable.
+- **Prefer fakes over mocks**: Tests use realistic substitutes (no `vi.mock()`).
+- **YAGNI with discipline**: No speculative abstractions.
+- **Architectural fixes over patches**: Reuse canonical parsing logic.
+- **Immutability by default**: `readonly` on all fields.
+
+**Potential conflict**: Creating write stubs on `FileSystemPortV2` is pragmatic but
+technically lies about the contract. The pitch (R1 mitigation) explicitly endorses this
+approach. Acceptable given the inline-construction pattern is already acknowledged as
+a special case.
+
+---
+
+## Impact Surface
+
+- `src/coordinators/pr-review.ts`: `CoordinatorDeps.spawnSession` (add optional 4th arg),
+  `contextAssembler?` optional field. Backward-compatible.
+- `src/daemon/workflow-runner.ts`: `buildSystemPrompt()` reads `trigger.context['assembledContextSummary']`.
+  No signature change needed -- `trigger.context` already typed as `Readonly<Record<string,unknown>>`.
+- `src/cli-worktrain.ts`: `spawnSession` impl forwards 4th arg; `contextAssembler` wired.
+- All existing tests that construct `CoordinatorDeps` fakes: safe (optional fields).
+- No changes to `src/mcp/` or `src/v2/durable-core/`.
+
+---
+
+## Candidates
+
+### Candidate A: Real local infra classes with minimal read-only shims (SELECTED)
+
+**Summary**: Construct `LocalDataDirV2`, `LocalDirectoryListingV2`, and
+`LocalSessionEventLogStoreV2` directly inside `infra.ts`. Create inline adapters:
+- `DirectoryListingOpsPortV2`: wraps `fs.promises.readdir` + `stat` with `okAsync/errAsync`
+- `FileSystemPortV2`: only `readFileUtf8` is real; write/fd methods throw 'context-assembly: write ops not supported'
+- `Sha256PortV2`: stub that throws (never called during `load()`)
+
+**Tensions resolved**: R1 (DI wiring scope). Uses battle-tested session loading and
+projection code. Neverthrow/custom Result bridge stays at `infra.ts` boundary only.
+
+**Tensions accepted**: Write stubs on `FileSystemPortV2` are a partial lie.
+
+**Boundary solved at**: `src/context-assembly/infra.ts` -- coordinator composition root.
+
+**Why this boundary is best-fit**: The coordinator is already a composition root
+(`src/cli-worktrain.ts` wires all real deps). `infra.ts` is a thin adapter layer that
+belongs exactly here.
+
+**Failure mode**: If `LocalSessionEventLogStoreV2.load()` ever internally calls a write
+method (unlikely but possible in future refactors), `infra.ts` would throw at runtime
+rather than returning `err()`. This would be caught immediately by tests.
+
+**Repo-pattern relationship**: Follows existing local infra pattern exactly.
+`LocalDataDirV2`, `LocalDirectoryListingV2`, `LocalSessionEventLogStoreV2` are already
+the canonical local implementations.
+
+**Gains**: Reuses battle-tested store loading and projection code. No risk of format
+divergence if session file structure changes.
+
+**Losses**: Write stubs feel slightly dishonest. Minor complexity in `infra.ts`.
+
+**Scope judgment**: Best-fit. Stays within `src/context-assembly/` with no v2 changes.
+
+**Philosophy fit**: Honors DI for boundaries (composition root pattern), errors-as-data
+(Result bridge), architectural fixes over patches (reuses canonical code). Minor
+tension with YAGNI (write stubs) and interface honesty.
+
+---
+
+### Candidate B: Read session files directly with fs.promises
+
+**Summary**: Skip the port hierarchy. Read `manifest.jsonl` and `events/*.jsonl` directly
+using `fs.promises.readFile`. Parse manually or reuse just the schema validators.
+
+**Tensions resolved**: R1 completely -- no DI wiring at all.
+
+**Tensions accepted**: Duplicates session reading logic. Any change to session file
+format requires updates in two places.
+
+**Failure mode**: Silent breakage if session file format changes.
+
+**Repo-pattern relationship**: Departs from established pattern (re-implements existing logic).
+
+**Scope judgment**: Too narrow -- creates a fragile parallel implementation.
+
+**Philosophy fit**: Conflicts with 'architectural fixes over patches'.
+
+---
+
+### Candidate C: Add createLocalSessionSummaryProvider() factory to v2 module
+
+**Summary**: Add a `createLocalSessionSummaryProvider()` factory function to
+`src/v2/infra/local/session-summary-provider/index.ts` that wires real deps and
+returns a `SessionSummaryProviderPortV2`. Import and call from `infra.ts`.
+
+**Tensions resolved**: Cleanest DI wiring.
+
+**Tensions accepted**: Modifies an existing v2 infra module.
+
+**Failure mode**: Entangles CLI-coordinator concerns into the storage layer.
+
+**Scope judgment**: Slightly too broad -- modifies v2 module with no functional benefit
+over Candidate A.
+
+---
+
+## Comparison and Recommendation
+
+**Recommendation: Candidate A**
+
+All candidates agree on the high-level approach (4 new files, 3 modified files, exact
+pitch interfaces). The only real design decision is `infra.ts` implementation.
+
+Candidate A wins because:
+1. It reuses battle-tested code for session reading and health projection
+2. It stays within `src/context-assembly/` -- no v2 module changes
+3. The write stubs are safe: `load()` provably does not call write methods
+4. The pitch explicitly endorses this approach as R1 mitigation
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument**: The write stubs on `FileSystemPortV2` create a silent
+contract violation. If a future `load()` implementation adds a write call internally,
+the error would surface at runtime (throw) rather than compile-time.
+
+**Narrower option that lost**: Candidate B (raw fs.promises). Lost because it duplicates
+canonical parsing logic and diverges from existing patterns.
+
+**Broader option and evidence required**: Candidate C would be justified if multiple
+other CLI commands needed access to session summaries -- adding a factory to the v2
+module would be worth the scope increase. No evidence of this need in v1.
+
+**Assumption that would invalidate this design**: If `LocalSessionEventLogStoreV2.load()`
+internally calls any of the stubbed write methods (currently provably false by code
+inspection of `loadImpl()`, `loadValidatedPrefixImpl()`, `readManifestOrEmpty()`).
+
+---
+
+## Open Questions for Main Agent
+
+1. Verify: does `Sha256PortV2` have a simple interface that can be satisfied with a
+   1-line `node:crypto` implementation? (If so, use real impl rather than throw stub.)
+2. Verify: does the `FileSystemPortV2` shim need anything beyond `readFileUtf8` for
+   the `load()` path? (Current analysis: no -- `readManifestOrEmpty` and segment loading
+   both use `readFileUtf8` only.)
+3. The re-review spawn (line ~1265 in pr-review.ts) should forward `spawnContext` from
+   the outer scope per the pitch. Confirm this is the correct approach (vs. reassembling
+   context for re-reviews).

package/docs/design/context-assembly-implementation-plan.md

@@ -0,0 +1,211 @@
+# Implementation Plan: Context Assembly Layer v1
+
+*Authored during coding-task-workflow-agentic session | 2026-04-19*
+
+---
+
+## Problem Statement
+
+When the PR review coordinator dispatches a session, it passes only a goal string.
+The agent spends its first 2-3 turns re-establishing context (re-reading PR diff,
+starting cold with no memory of prior reviews). Before spawning each session, the
+coordinator should assemble a context bundle (git diff summary + prior session notes)
+and inject it into the system prompt via the existing `trigger.context` map.
+
+---
+
+## Acceptance Criteria
+
+1. `npm run build` compiles clean with zero TypeScript errors
+2. `npx vitest run tests/unit/context-assembly.test.ts` -- all 5 tests pass
+3. `npx vitest run` -- no regressions in full test suite
+4. New module `src/context-assembly/` exists with 4 files
+5. `CoordinatorDeps.contextAssembler?` optional field present
+6. `CoordinatorDeps.spawnSession` accepts optional 4th `context?` arg
+7. `buildSystemPrompt()` injects `## Prior Context` section when `assembledContextSummary` present in trigger context
+8. `src/cli-worktrain.ts` wires `contextAssembler` and forwards `context` through HTTP body
+
+---
+
+## Non-Goals
+
+1. No URL fetching from PR description bodies (v2)
+2. No full git diff content -- `--stat` output only
+3. No changes to `src/mcp/` or `src/v2/durable-core/`
+4. No knowledge graph source (`ts-morph` stays in devDependencies)
+5. No per-coordinator custom renderers
+6. No context window budget trimming
+7. No context assembly in `TriggerRouter.route()`
+8. No HTTP endpoint schema changes
+9. No workspace-scoped session filtering (v1 returns global sessions)
+
+---
+
+## Philosophy-Driven Constraints
+
+- All interface fields `readonly` (immutability by default)
+- `Result<T,E>` (`kind: 'ok'|'err'`) for all new code; bridge from neverthrow at `infra.ts` boundary
+- Factory function `createContextAssembler()`, not a class
+- `renderContextBundle()` is pure (no I/O)
+- `ContextAssemblerDeps` interface contains all I/O; core has zero direct imports of `fs`/`execFile`
+- Tests: fake deps, no `vi.mock()`, vitest `describe/it/expect`
+- Import paths use `.js` extension (TypeScript ESM)
+- JSDoc `WHY` comments on non-obvious decisions
+
+---
+
+## Invariants
+
+1. **Partial failure**: `gitDiff` and `priorSessionNotes` fail independently; session always starts
+2. **Zero agent turn cost**: Context injected in system prompt before turn 1
+3. **Coordinator-controlled opt-in**: Only coordinators calling `assembler.assemble()` get enriched context
+4. **Prior notes recency limit**: At most 3 prior sessions
+5. **Git summary size**: File names and change counts only (no full diff)
+6. **No engine/MCP changes**: `src/v2/durable-core/` and `src/mcp/` untouched
+7. **Optional contextAssembler**: Backward-compatible -- all existing `CoordinatorDeps` fakes work
+
+---
+
+## Selected Approach
+
+Use 4 new files in `src/context-assembly/` + 3 modified files, exactly as specified in
+the pitch. `infra.ts` uses a direct `SessionEventLogReadonlyStorePortV2` adapter
+(implementing only `load()` and `loadValidatedPrefix()` via `fs.promises` + existing Zod
+schemas) instead of `LocalSessionEventLogStoreV2`. This eliminates the need for
+`FileSystemPortV2` and `Sha256PortV2` shims.
+
+**Runner-up**: Use `LocalSessionEventLogStoreV2` with write stubs. Rejected: write stubs
+partially violate the interface contract even though they're provably unreachable.
+
+---
+
+## Vertical Slices
+
+### Slice 1: New module `src/context-assembly/` (4 files)
+
+**Files to create**:
+- `src/context-assembly/types.ts` (~60 LOC) - AssemblyTask, SessionNote, ContextBundle, RenderOpts, ContextAssembler interface
+- `src/context-assembly/deps.ts` (~35 LOC) - ContextAssemblerDeps interface (execGit, execGh, listRecentSessions, nowIso)
+- `src/context-assembly/index.ts` (~80 LOC) - createContextAssembler(), renderContextBundle(), private helpers
+- `src/context-assembly/infra.ts` (~80 LOC) - createListRecentSessions() adapter
+
+**Done when**: All 4 files compile clean in isolation
+
+**Key implementation details**:
+- `types.ts`: import `Result` from `'../runtime/result.js'`
+- `index.ts`: factory function `createContextAssembler(deps)`, pure `renderContextBundle(bundle, _opts?)`
+- `infra.ts`: `SessionEventLogReadonlyStorePortV2` adapter using `fs.promises.readFile` + `ManifestRecordV1Schema` + `DomainEventV1Schema`; `LocalDataDirV2(process.env)` + `LocalDirectoryListingV2(directoryListingOpsAdapter)` wired into `LocalSessionSummaryProviderV2`
+- `infra.ts`: `_workspacePath` named with leading underscore (intentional non-use in v1)
+- Bridge: `const result = await provider.loadHealthySummaries(); if (result.isErr()) return err(...);`
+
+### Slice 2: Modify `src/coordinators/pr-review.ts`
+
+**Changes**:
+1. Add `contextAssembler?: ContextAssembler` field to `CoordinatorDeps` (after `spawnSession`, before `awaitSessions`)
+2. Extend `spawnSession` signature: add optional 4th arg `context?: Readonly<Record<string, unknown>>`
+3. Add context assembly block before `spawnSession` call in `runPrReviewCoordinator` for-loop
+4. Forward same `spawnContext` to re-review spawn (~line 1265)
+5. Do NOT add context assembly to fix-agent spawn
+
+**Done when**: File compiles clean; existing tests still pass
+
+### Slice 3: Modify `src/daemon/workflow-runner.ts`
+
+**Change**: Insert 6-line block in `buildSystemPrompt()` BEFORE the `referenceUrls` block
+
+**Done when**: File compiles clean; `buildSystemPrompt` tests (if any) still pass
+
+### Slice 4: Modify `src/cli-worktrain.ts`
+
+**Changes**:
+1. Add imports for `createContextAssembler` and `createListRecentSessions`
+2. Extend `spawnSession` lambda to accept optional 4th `context?` arg and include it in JSON body
+3. Add `contextAssembler: createContextAssembler({...})` to deps object (after `spawnSession`)
+4. Wire `execGit`, `execGh` inline using `promisify(execFile)`
+
+**Done when**: File compiles clean
+
+### Slice 5: Tests
+
+**File**: `tests/unit/context-assembly.test.ts`
+
+**Tests**:
+1. `assemble()` with both sources succeeding -- returns bundle with `kind: 'ok'` on both fields
+2. `assemble()` with gitSummary failing -- priorNotes still returns `ok([])`; gitDiff returns `kind: 'err'`
+3. `renderBundle()` produces correct markdown sections (headings, git diff in code block)
+4. `renderBundle()` with all-failed bundle -- returns empty string
+5. `listRecentSessions` with no sessions directory -- returns `ok([])`
+
+**Done when**: All 5 tests pass with `npx vitest run tests/unit/context-assembly.test.ts`
+
+---
+
+## Test Design
+
+### Fake deps for context assembler
+
+```typescript
+function makeFakeDeps(overrides: Partial<ContextAssemblerDeps> = {}): ContextAssemblerDeps {
+  return {
+    execGit: async () => ({ kind: 'ok', value: 'src/foo.ts | 5 ++\n' }),
+    execGh: async () => ({ kind: 'err', error: 'gh not available' }),
+    listRecentSessions: async () => ({ kind: 'ok', value: [] }),
+    nowIso: () => '2026-04-19T00:00:00.000Z',
+    ...overrides,
+  };
+}
+```
+
+### Test for no sessions directory
+
+Uses a real temp directory (with no sessions subdirectory) to test the graceful `ok([])` return.
+
+---
+
+## Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|---|---|---|---|
+| `infra.ts` SessionEventLogReadonlyStorePortV2 adapter has parsing bugs | Low | Medium | Tests verify behavior with fake data; manifest format well-documented |
+| `spawnSession` 4th arg breaks existing tests | Very Low | Low | Optional arg; TypeScript enforces backward compat |
+| `contextAssembler` not optional breaks existing tests | Very Low | Low | `?` makes it optional; existing fakes compile without it |
+| Full test suite regressions | Very Low | High | Run `npx vitest run` before PR |
+
+---
+
+## PR Packaging Strategy
+
+**Single PR**: `feat/context-assembly-layer`
+
+All 7 file changes ship together. They form a single coherent feature -- the 4 new
+files are meaningless without the 3 modifications, and the modifications are safe
+with or without the new files.
+
+**Commit message**: `feat(coordinator): add context assembly layer -- git summary and prior session notes`
+
+---
+
+## Philosophy Alignment Per Slice
+
+| Slice | Principle | Status |
+|---|---|---|
+| Slice 1 (types) | Make illegal states unrepresentable (discriminated union) | Satisfied |
+| Slice 1 (index) | Functional/declarative (factory fn, pure render) | Satisfied |
+| Slice 1 (infra) | DI for boundaries (all I/O behind interface) | Satisfied |
+| Slice 1 (infra) | Architectural fixes over patches (reuse projection code) | Satisfied |
+| Slice 2 (coordinator) | Errors are data (Result<T,E>) | Satisfied |
+| Slice 2 (coordinator) | Backward compatibility via optional fields | Satisfied |
+| Slice 3 (workflow-runner) | Validate at boundaries (type check before inject) | Satisfied |
+| Slice 5 (tests) | Prefer fakes over mocks | Satisfied |
+
+---
+
+## Open Questions (Residual)
+
+None. All questions were resolved during design review:
+1. `ManifestRecordV1Schema` and `DomainEventV1Schema` -- confirmed exported
+2. `asSessionId` -- confirmed exported from ids/index.ts
+3. Re-review spawn context -- confirmed: forward same `spawnContext` from outer scope
+
+**`unresolvedUnknownCount`**: 0
+**`planConfidenceBand`**: High

package/docs/design/context-assembly-review-findings.md

@@ -0,0 +1,112 @@
+# Design Review Findings: Context Assembly Layer v1
+
+*Generated during coding-task-workflow-agentic session | 2026-04-19*
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Verdict | Condition for Failure |
+|---|---|---|
+| FileSystemPortV2 write stubs | RESOLVED -- switching to direct SessionEventLogReadonlyStorePortV2 adapter | N/A |
+| Inline DI wiring in infra.ts | Acceptable -- explicitly endorsed by pitch R1 mitigation | N/A |
+| Global session list (no workspace filtering) | Accepted -- v2 improvement documented in pitch | Multiple simultaneous workspaces with unrelated sessions |
+| Promise.all partial failure | Adequately handled -- each source returns Result, try/catch in infra | N/A |
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Covered By | Residual Risk |
+|---|---|---|
+| Write stubs called | Outer try/catch in createListRecentSessions | Low -- FM1 resolved by switching adapter |
+| Git commands fail | execGit/execGh return err(), fallback chain | None |
+| Sessions dir missing | LocalDirectoryListingV2 returns [] for FS_NOT_FOUND | None |
+| Corrupt session data | LocalSessionSummaryProviderV2 graceful skip | None |
+| spawnSession backward compat | Optional 4th arg | None |
+| contextAssembler not provided | Optional field + if-guard in coordinator | None |
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+**Runner-up** (Candidate B: raw fs.promises) has no elements worth borrowing into the
+selected design.
+
+**Simpler variant identified**: Use a direct `SessionEventLogReadonlyStorePortV2`
+adapter in `infra.ts` instead of `LocalSessionEventLogStoreV2`. This eliminates all
+`FileSystemPortV2` and `Sha256PortV2` stubs while still reusing `LocalSessionSummaryProviderV2`
+and the full projection pipeline. The adapter implements only `load()` and
+`loadValidatedPrefix()` using `fs.promises` + existing Zod schemas (`ManifestRecordV1Schema`,
+`DomainEventV1Schema`). Approximately 40 lines. This is strictly cleaner.
+
+**Recommendation**: Use the simpler `SessionEventLogReadonlyStorePortV2` adapter approach.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Alignment |
+|---|---|
+| Errors are data | STRONG -- Result<T,E> throughout |
+| DI for boundaries | STRONG -- ContextAssemblerDeps, inline construction accepted for separate process |
+| Prefer fakes over mocks | STRONG -- test spec uses fake deps |
+| Immutability by default | STRONG -- readonly everywhere |
+| Make illegal states unrepresentable | STRONG -- AssemblyTask discriminated union |
+| Functional/declarative | STRONG -- factory functions, pure renderContextBundle |
+| YAGNI | MILD TENSION -- empty RenderOpts interface (accepted, documented) |
+| Architectural fixes over patches | STRONG with adapter approach |
+
+---
+
+## Findings
+
+### YELLOW: Empty RenderOpts interface
+
+**Severity**: Yellow (minor)
+
+**Finding**: `RenderOpts` is an empty interface in v1. TypeScript `{}` and `interface RenderOpts {}` are equivalent. The empty interface is only useful as a future extension point.
+
+**Assessment**: Acceptable -- the pitch explicitly documents this as an intentional v1 placeholder. No action needed.
+
+### YELLOW: Global session filtering (no workspace scope)
+
+**Severity**: Yellow (minor, known)
+
+**Finding**: `listRecentSessions` returns the 3 most recent sessions globally, not scoped to the coordinator's workspace path. For users running multiple workspaces, prior notes from unrelated workspaces may appear.
+
+**Assessment**: Acceptable for v1 -- pitch explicitly documents this as a known limitation. The `_workspacePath` parameter should be named with a leading `_` to signal intentional non-use.
+
+### GREEN: All other design elements
+
+Tradeoffs, failure modes, and philosophy alignment are all sound. No RED or ORANGE findings.
+
+---
+
+## Recommended Revisions
+
+1. **Use direct `SessionEventLogReadonlyStorePortV2` adapter** in `infra.ts` instead of
+   `LocalSessionEventLogStoreV2`. Eliminates all write stubs. Implements `load()` using
+   `fs.promises.readFile` + `ManifestRecordV1Schema` + `DomainEventV1Schema` parsing.
+   Approximately 40 lines.
+
+2. **Name unused parameter** `_workspacePath` in `createListRecentSessions` to signal
+   intentional non-use.
+
+---
+
+## Residual Concerns
+
+1. **Import path for Zod schemas**: `ManifestRecordV1Schema` and `DomainEventV1Schema`
+   must be importable from `src/v2/durable-core/schemas/session/index.ts`. Verify before
+   implementing that these schemas are exported.
+
+2. **`asSessionId` usage**: The `SessionEventLogReadonlyStorePortV2.load()` adapter
+   receives a `SessionId` branded type. When reading session directories and mapping
+   entry names to `SessionId`, the `asSessionId` import from
+   `src/v2/durable-core/ids/index.ts` must be used correctly.
+
+3. **Neverthrow ResultAsync wrapping**: The adapter must return neverthrow `ResultAsync`
+   objects (using `okAsync`/`errAsync` from neverthrow), not the custom `Result` type.
+   The bridge from neverthrow to custom Result happens in the `createListRecentSessions`
+   function via `const result = await resultAsync; if (result.isErr()) return err(...)`.