@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/plans/native-context-management-epic.md

@@ -0,0 +1,11 @@
+# Epic: Native Context Management for Workflows
+
+> **Not pursuing**
+>
+> WorkRail is not planning to implement native context management.
+>
+> This file is kept only as a stable tombstone so old references do not break.
+>
+> Use these instead:
+> - `docs/roadmap/legacy-planning-status.md`
+> - `docs/roadmap/open-work-inventory.md`

package/docs/plans/perf-fixes-design-candidates.md

@@ -0,0 +1,225 @@
+# Performance Fixes: Design Candidates
+
+**Context:** Four remaining performance fixes after a prior session implemented expanded skip list,
+`MAX_WALK_DEPTH=5`, and 30s TTL walk cache.
+
+---
+
+## Problem Understanding
+
+### Core tensions
+
+1. **Determinism vs. performance** (findWorkflowJsonFiles parallelization): Making directory scan
+   concurrent breaks output insertion order. Resolved by sorting the result -- adds negligible
+   overhead at realistic file counts.
+
+2. **Simplicity vs. targeted protection** (timeout on walk): The simplest placement wraps all of
+   `createWorkflowReaderForRequest`. But the walk is only one sub-phase -- a tighter, more targeted
+   timeout should wrap just `discoverRootedWorkflowDirectories`.
+
+3. **Lazy vs. eager eviction** (TTL in remembered roots): Lazy eviction (on write) is simple and
+   has no background-timer risk. It only runs when `rememberRoot` is called, so a workspace seen
+   once and never evicted persists until the next write. Acceptable per issue #241.
+
+4. **Real I/O vs. mocked infra** (latency test): A test using real `fs.mkdir` can be slow on CI.
+   A 500ms budget for a small synthetic tree is generous enough to avoid flakiness.
+
+### Likely seam
+
+- **Parallelization**: inside `scan()` in `findWorkflowJsonFiles` -- collect subdirs, fan out with
+  `Promise.all`, sort final `files` array.
+- **Timeout**: inside `createWorkflowReaderForRequest` wrapping `discoverRootedWorkflowDirectories`
+  -- single place, both handlers automatically protected.
+- **TTL eviction**: inside the `andThen` chain in `rememberRoot()`, just before
+  `this.persist(nextRoots)` -- lock is already held, `nextRoots` already computed.
+- **Latency test**: `tests/performance/perf-fixes.test.ts` following `cache-eviction.test.ts` style.
+
+### What makes this hard
+
+- Parallelization + determinism: need explicit sort, not just `Promise.all`
+- Timeout constant calibration: 10s is generous for most environments but may be tight on
+  cold-start NFS mounts before the 30s cache warms
+- TTL eviction placement: must be on write path (not read path) to avoid per-call overhead
+- Latency test flakiness: tree must be small enough to be fast on CI, large enough to exercise
+  the depth limit
+
+---
+
+## Philosophy Constraints
+
+From `AGENTS.md` and `/Users/etienneb/CLAUDE.md`:
+
+- **Determinism over cleverness**: parallelization requires explicit sort to restore determinism
+- **Errors are data**: `withTimeout` throws; callers use `ResultAsync.fromPromise(withTimeout(...))`
+  -- no change to that pattern needed
+- **Immutability by default**: TTL filter produces a new `nextRoots` array (does not mutate)
+- **YAGNI with discipline**: no configurable TTL parameter -- use a named constant
+- **Prefer fakes over mocks**: latency test uses real `fs` operations
+- **Document 'why', not 'what'**: TTL constant and parallelization rationale need explanatory
+  comments
+
+### Conflicts
+
+- **Stated: no exceptions** vs **practiced: `withTimeout` throws**. Consistent in practice:
+  `withTimeout` is a low-level utility; callers convert at boundary with `ResultAsync.fromPromise`.
+
+---
+
+## Impact Surface
+
+- `findWorkflowJsonFiles` is called by `scanRawWorkflowFiles` (same file). No caller asserts
+  order today. Sort makes the new order contract explicit and stable.
+- `createWorkflowReaderForRequest` is called from `handleV2ListWorkflows` and
+  `handleV2InspectWorkflow`. Adding timeout inside the shared function protects both handlers
+  without modifying them.
+- `rememberRoot` is called from `remembered-roots.ts` shared handler helper -- no interface
+  change needed.
+- `LocalRememberedRootsStoreV2` implements `RememberedRootsStorePortV2` -- port interface
+  unchanged.
+
+---
+
+## Candidates
+
+### Item 1: Parallelize `findWorkflowJsonFiles`
+
+#### Candidate A (recommended): `Promise.all` fan-out + final sort
+
+Inside `scan()`, collect subdirectory paths from `entries`, push files immediately, then
+`await Promise.all(subdirs.map(dir => scan(dir)))`. After `scan(baseDirReal)` returns, call
+`files.sort()` before return.
+
+- **Tensions resolved**: sequential scan latency
+- **Tensions accepted**: minor sort overhead (negligible)
+- **Boundary**: inside `scan()`, no interface change
+- **Why best-fit**: targets the anti-pattern directly
+- **Failure mode**: if a caller depends on insertion order (none currently do)
+- **Repo pattern**: follows `Promise.all` fan-out used elsewhere
+- **Gain**: concurrent I/O; **Lose**: insertion order (replaced by stable sort)
+- **Scope**: best-fit
+- **Philosophy**: honors Determinism (via sort), Compose with small pure functions
+
+#### Candidate B: Replace `statSync` with async `fs.stat`, keep sequential loop
+
+Replaces the blocking sync call in the scan loop with async stat, but keeps sequential descent.
+
+- Too narrow: doesn't fix the `for...of await` sequential descent -- the main bottleneck
+- **Scope**: too narrow
+
+---
+
+### Item 2: Timeout protection for walk
+
+#### Candidate A (recommended): Wrap `discoverRootedWorkflowDirectories` inside `createWorkflowReaderForRequest`
+
+Add `DISCOVERY_TIMEOUT_MS = 10_000` constant. Replace:
+```ts
+const { discovered, stale } = await discoverRootedWorkflowDirectories(rememberedRoots);
+```
+with:
+```ts
+const { discovered, stale } = await withTimeout(
+  discoverRootedWorkflowDirectories(rememberedRoots),
+  DISCOVERY_TIMEOUT_MS,
+  'workflow_root_discovery',
+);
+```
+
+- **Tensions resolved**: hung walk blocking handler forever; single place to maintain
+- **Boundary**: `createWorkflowReaderForRequest` in shared module
+- **Failure mode**: 10s may be tight on cold NFS walk -- mitigated by 30s cache for subsequent calls
+- **Repo pattern**: adapts exact same `withTimeout` pattern from `v2-workflow.ts` lines 215/363
+- **Scope**: best-fit
+
+#### Candidate B: Wrap `createWorkflowReaderForRequest` in each handler
+
+Two call sites. If a 3rd handler is added, it misses the timeout. Departs from DRY.
+
+- **Scope**: too broad (and duplicated)
+
+---
+
+### Item 3: TTL eviction in `LocalRememberedRootsStoreV2`
+
+#### Candidate A (recommended): Filter `nextRoots` in `rememberRoot()` before persist
+
+Add `const TTL_30_DAYS_MS = 30 * 24 * 60 * 60 * 1000`. In `rememberRoot()`:
+
+```ts
+const withEviction = nextRoots.filter(
+  (root) => root.lastSeenAtMs >= nowMs - TTL_30_DAYS_MS
+);
+return this.persist(withEviction);
+```
+
+- **Boundary**: inside `rememberRoot()`, lock already held, `nextRoots` already computed
+- **Failure mode**: roots seen once and never evicted until next write -- acceptable
+- **Repo pattern**: adapts `normalizeRootRecords` filter pattern in same file
+- **Philosophy**: Immutability (new filtered array), YAGNI (no configurable TTL)
+
+#### Candidate B: Filter in `listRootRecords()` (read path)
+
+Eviction on read removes stale entries from the in-memory result but does not persist them.
+Stale entries remain on disk. Read path is called much more often -- wrong seam.
+
+- **Scope**: wrong boundary; doesn't reduce disk accumulation
+
+---
+
+### Item 4: Latency regression test
+
+#### Candidate A (recommended): Synthetic tree in `tests/performance/perf-fixes.test.ts`
+
+Create a temp directory tree (depth 5, branching factor 3) with real `fs.mkdir`. Call
+`discoverRootedWorkflowDirectories([treeRoot])`. Assert elapsed < 500ms.
+
+- **Boundary**: black-box test of the exported function
+- **Failure mode**: flaky on slow CI if tree is too large -- mitigated by small breadth (3) and depth (5)
+- **Repo pattern**: follows `cache-eviction.test.ts` style
+- **Philosophy**: Prefer fakes over mocks (real FS); Determinism (reproducible tree)
+
+---
+
+## Comparison and Recommendation
+
+All candidates converge. Genuine diversity does not exist for these changes -- each problem has
+one clearly best-fit mechanical solution.
+
+**Proceed with all four Candidate A choices.**
+
+Each change:
+- Touches exactly one function
+- Requires no interface or contract changes
+- Is reversible (one-line revert if assumptions are wrong)
+- Follows an existing repo pattern
+
+---
+
+## Self-Critique
+
+### Strongest counter-arguments
+
+- **Parallelization**: if downstream validation depends on processing order, sorting may not be
+  enough and could mask a latent ordering bug. No test currently asserts order -- low risk.
+- **Walk timeout at 10s**: first cold walk on a large monorepo on NFS might legitimately exceed 10s.
+  Would produce a user-visible timeout error on first use. The 30s cache means subsequent calls
+  are instant -- only the first call is at risk.
+
+### Pivot conditions
+
+- If cold walk times > 10s in production: raise `DISCOVERY_TIMEOUT_MS` or add per-root timeout
+  inside `walkForRootedWorkflowDirectories`.
+- If `findWorkflowJsonFiles` results need filesystem order: remove sort, document non-determinism.
+- If TTL eviction needs to run on stale roots that are never written again: add eviction to the
+  read path as a side-effecting read or add a separate `evictStaleRoots()` method.
+
+### Narrower option that lost
+
+Sequential `findWorkflowJsonFiles` with only `statSync` → `fs.stat`: fixes minor blocking I/O
+but doesn't address the actual sequential descent anti-pattern.
+
+---
+
+## Open Questions
+
+None that require human decision. All design choices are bounded by existing constraints.

package/docs/plans/perf-fixes-design-review-findings.md

@@ -0,0 +1,61 @@
+# Performance Fixes: Design Review Findings
+
+## Tradeoff Review
+
+| Tradeoff | Verdict | Notes |
+|---|---|---|
+| Lazy TTL eviction (write-only) | Acceptable | Issue #241 explicitly allows lazy eviction. Roots not written again persist, but this is a known, bounded edge case. |
+| Non-deterministic intermediate state during parallel scan | Acceptable | Resolved by final `files.sort()` -- stable lexicographic order. No caller asserts insertion order. |
+| 10s walk timeout may be tight on slow FS | Acceptable | 30s cache means only first cold call is at risk. Error is descriptive, not silent. Constant is easy to raise. |
+
+## Failure Mode Review
+
+| Failure Mode | Coverage | Residual Risk |
+|---|---|---|
+| Order dependency in callers after parallelization | Covered by sort | Low |
+| Walk timeout fires on first cold call | Descriptive error, user recovers | Medium (UX degradation, not data loss) |
+| TTL eviction false positive (active root evicted) | Impossible at 30-day TTL | None |
+| Latency test flakiness (cache interference) | Mitigated: unique temp dir per test run | Low |
+
+## Runner-Up / Simpler Alternative Review
+
+No runner-up elements worth pulling. No simpler alternative satisfies all acceptance criteria.
+All four Candidate A approaches remain unchanged.
+
+## Philosophy Alignment
+
+All key principles satisfied: Determinism (via sort), Errors are data (ResultAsync.fromPromise
+wrapping), Immutability (new arrays), YAGNI (named constants), Prefer fakes over mocks (real FS
+in test), Architectural fixes over patches (parallelization, timeout).
+
+Two minor tensions:
+- `files[]` shared append in parallel scan: acceptable in single-threaded Node.js
+- Timeout inside utility function vs. handler boundary: acceptable -- shared module IS the discovery boundary
+
+## Findings
+
+**Yellow: Walk timeout constant (10s) has no empirical basis**
+- DISCOVERY_TIMEOUT_MS = 10_000 is a reasonable default but untested against real environments
+- Should be commented as adjustable, not hardcoded as final
+- No blocking concern for this PR; monitor in production
+
+**Yellow: Latency test timing assertion (500ms) is generous for a small tree but may pass vacuously**
+- A 500ms budget for a depth-5 breadth-3 tree (max ~243 dirs) should complete in ~10-50ms
+- The test is more valuable as a non-regression guard than a strict budget test
+- Document the budget reasoning in the test comment
+
+No Red or Orange findings.
+
+## Recommended Revisions
+
+1. Add a comment near `DISCOVERY_TIMEOUT_MS` explaining it can be raised for slow NFS environments
+2. Add a comment in the latency test explaining the 500ms budget and tree size rationale
+3. Use a unique temp dir per test invocation (already in plan) to prevent walk cache interference
+
+## Residual Concerns
+
+- **Walk timeout vs. UX**: if production walk times are measured and commonly > 10s, the constant
+  should be raised to 20s. No action needed now.
+- **TTL eviction completeness**: roots that are never written again persist forever. Acceptable
+  per issue #241. If this becomes a problem, a separate `evictStaleRoots()` method would be the
+  right extension point.

package/docs/plans/perf-fixes-new-issues-candidates.md

@@ -0,0 +1,264 @@
+# Performance Fixes: New Issues Discovery
+
+**Date:** 2026-04-07
+**Status:** Complete -- 5 new issues confirmed, HIGH confidence
+
+## Final Summary
+
+**Path:** full_spectrum (landscape reading + reframing)
+
+**Problem framing:** The known 7 issues were derived from design doc analysis. Actual source code reading reveals 5 additional issues: one second unguarded call site (inspect_workflow), one test comment that describes nonexistent code, and three issues in `raw-workflow-file-scanner.ts` (a file the known list doesn't mention).
+
+**Landscape takeaways:** All 4 target files are in pre-fix state. No implemented fixes. The design patterns for all fixes exist elsewhere in the codebase (`withTimeout` in v2-workflow.ts, `normalizeRootRecords` in the same remembered-roots file, `Promise.all` fan-out referenced in design docs, `sortedEntries` in request-workflow-reader.ts).
+
+**Chosen direction:** All 5 new issues are confirmed and distinct. No single 'direction' -- this is a discovery output.
+
+**Confidence band:** HIGH
+
+**Residual risks:**
+1. Issue A severity: if MCP transport already converts unhandled promise rejections to structured error responses, Issue A is degraded-response rather than crash. Verify before classifying as Red.
+2. Issue C scope: `existsSync` is imported alongside `statSync` at raw-workflow-file-scanner.ts:2 -- audit its usage for the same event-loop concern.
+
+**Next actions:**
+1. Add Issue A to the known issue #1 ticket (or create a sub-item): inspect_workflow call site at v2-workflow.ts:332
+2. Create a new ticket for raw-workflow-file-scanner.ts covering Issues C, D, E together (they are all in the same file)
+3. Fix Issue B (test comment) as part of whichever PR implements the walk cache
+
+This document records issues found by reading the actual current state of the four target files
+(`request-workflow-reader.ts`, `raw-workflow-file-scanner.ts`, `remembered-roots-store/index.ts`,
+`perf-fixes.test.ts`). All 7 previously known issues are confirmed present. The 5 issues below
+are NEW -- not named in the known list.
+
+---
+
+## Problem Understanding
+
+### Core tensions
+
+1. **Known list completeness vs. actual code state**: The known 7 issues were derived from design
+   doc analysis. Reading actual code reveals additional gaps that the design docs mentioned but the
+   known issue list didn't capture explicitly.
+
+2. **Fix scope vs. fix surface**: The design docs say 'all changes in request-workflow-reader.ts'
+   for the walk fixes, but the unguarded call site issue extends to `handleV2InspectWorkflow` --
+   a second handler not named in known issue #1.
+
+3. **Test reliability vs. test accuracy**: The test file describes code behavior that doesn't exist
+   yet (a walk cache), creating a maintenance hazard for future implementers.
+
+### Likely seam
+
+- Issues A (call site): `v2-workflow.ts` lines 332-339 -- identical structural pattern to known issue #1
+- Issues B (test comment): `perf-fixes.test.ts` lines 17-18 -- inline comment describing phantom cache
+- Issues C, D, E (scanner): `raw-workflow-file-scanner.ts` -- all three affect the same file,
+  different functions: `statSync` at line 95, `scan()` sequential loop lines 19-35, unsorted return
+
+### What makes this hard
+
+- Issue A is easy to miss because the design doc says 'callers need not change' -- but it was
+  wrong: there are two bare-await call sites, not one
+- Issue B is invisible unless you cross-check test comments against actual source code
+- Issues C/D/E all live in `raw-workflow-file-scanner.ts` -- a file the known issues don't mention,
+  even though the design doc explicitly specifies all three fixes for it
+
+---
+
+## Philosophy Constraints
+
+- **Errors are data**: Issue A violates this -- `createWorkflowReaderForRequest` can throw, and
+  `handleV2InspectWorkflow` doesn't wrap it in a Result
+- **Determinism over cleverness**: Issue E violates this -- filesystem readdir order is not stable
+- **Document why not what**: Issue B violates this -- the comment describes a thing that doesn't
+  exist, not the reason the test is structured as it is
+- **Dependency injection for boundaries**: Issue C violates this tangentially -- `statSync` is a
+  hidden sync I/O side effect inside an async function
+
+---
+
+## Impact Surface
+
+- **Issue A**: `handleV2InspectWorkflow` in `v2-workflow.ts` -- any `listRememberedRoots` error
+  thrown inside `createWorkflowReaderForRequest` reaches the MCP transport layer unhandled.
+  `handleV2ListWorkflows` has the same exposure (known issue #1). `start.ts` is correctly wrapped.
+
+- **Issue B**: `perf-fixes.test.ts` -- the misleading comment affects any future developer
+  implementing the walk cache. They might skip writing cache tests because the comment implies
+  the test already validates cache behavior.
+
+- **Issues C/D/E**: `raw-workflow-file-scanner.ts` affects `FileWorkflowStorage.buildWorkflowIndex`
+  (via `findWorkflowJsonFiles`) and `scanRawWorkflowFiles` (which calls `findWorkflowJsonFiles`
+  then does per-file reads). Both callers receive non-deterministic, sequentially-scanned results.
+
+---
+
+## New Issues
+
+### Issue A: `handleV2InspectWorkflow` has the same unguarded call site as the known #1
+
+**Summary:** `v2-workflow.ts` line 332 uses bare `await createWorkflowReaderForRequest(...)` in
+`handleV2InspectWorkflow`, identical to the known issue at line 193 in `handleV2ListWorkflows`.
+
+- **Tensions resolved**: names the second unguarded call site
+- **Tensions accepted**: requires the same fix pattern as known issue #1
+- **Boundary**: `v2-workflow.ts:332` -- the `handleV2InspectWorkflow` function
+- **Failure mode**: `listRememberedRoots` error propagates as unhandled exception to MCP transport
+- **Repo pattern**: `start.ts` correctly uses `RA.fromPromise(createWorkflowReaderForRequest(...), mapper)` -- that is the right pattern
+- **Gains**: fixing this gives complete handler coverage; losing it means inspect_workflow crashes on remembered-roots store errors
+- **Scope**: best-fit -- single line change at the call site
+- **Philosophy fit**: fixing restores 'Errors are data'
+
+**Evidence**: `src/mcp/handlers/v2-workflow.ts` line 332:
+```ts
+? await createWorkflowReaderForRequest({
+```
+vs `src/mcp/handlers/v2-execution/start.ts` line 364:
+```ts
+? RA.fromPromise(
+    createWorkflowReaderForRequest({...}),
+    (err): StartWorkflowError => ({...})
+  )
+```
+
+---
+
+### Issue B: Test file comment describes a walk cache that does not exist
+
+**Summary:** `perf-fixes.test.ts` lines 17-18 describe 'the module-level walk cache (keyed on
+sorted root paths)' -- a data structure that is entirely absent from `request-workflow-reader.ts`.
+
+- **Tensions resolved**: names the maintenance hazard
+- **Tensions accepted**: fix is purely editorial (update the comment)
+- **Boundary**: `tests/performance/perf-fixes.test.ts` -- the test file JSDoc block
+- **Failure mode**: future implementer reads the comment, assumes the cache is already tested,
+  and ships the cache implementation without writing cache hit/miss/TTL tests
+- **Repo pattern**: departs from 'Document why not what' -- should describe why unique temp dirs
+  are used (to prevent cross-test interference), not describe a feature that doesn't exist
+- **Scope**: best-fit -- comment update only
+- **Philosophy fit**: violation of 'Document why not what'
+
+**Evidence**: `tests/performance/perf-fixes.test.ts` lines 17-18:
+```
+* Each test uses a unique mkdtemp path so the module-level walk cache
+* (keyed on sorted root paths) does not mask the actual walk cost.
+```
+No cache exists anywhere in `request-workflow-reader.ts`.
+
+---
+
+### Issue C: `statSync` in `scanRawWorkflowFiles` blocks the Node.js event loop
+
+**Summary:** `raw-workflow-file-scanner.ts` line 95 uses the synchronous `statSync` inside an
+async function, blocking the event loop during file size checks.
+
+- **Tensions resolved**: eliminates the sync I/O stall
+- **Tensions accepted**: requires replacing with `await fs.stat(...)`
+- **Boundary**: `scanRawWorkflowFiles` inner loop, line 95
+- **Failure mode**: in the current state, every file in a workflow directory causes an event-loop stall during `scanRawWorkflowFiles` -- under concurrent load, all in-flight requests pause
+- **Repo pattern**: `fs/promises` is already imported at line 1; `statSync` and `existsSync` are imported from `'fs'` at line 2. Switching to async stat removes the sync import.
+- **Scope**: best-fit -- one-line replacement
+- **Philosophy fit**: violates async contract ('Determinism over cleverness', implicit event-loop contract)
+
+**Evidence**: `src/application/use-cases/raw-workflow-file-scanner.ts` line 2 and 95:
+```ts
+import { existsSync, statSync } from 'fs';
+...
+const stats = statSync(filePath);
+```
+The design doc (perf-fixes-design-candidates.md, Candidate B note) mentions replacing `statSync`
+with async `fs.stat`.
+
+---
+
+### Issue D: `findWorkflowJsonFiles` uses sequential `await` inside a `for` loop (no parallelization)
+
+**Summary:** `raw-workflow-file-scanner.ts` lines 19-35 implement `scan()` as a sequential
+`for...of` loop with `await scan(fullPath)` inside -- each subdirectory is fully scanned before
+the next one starts.
+
+- **Tensions resolved**: names the sequential I/O bottleneck in the scanner
+- **Tensions accepted**: parallelization requires explicit sort to restore deterministic order
+- **Boundary**: `scan()` inner function inside `findWorkflowJsonFiles`, lines 19-35
+- **Failure mode**: on a deep workflow directory with many subdirectories, scan is O(depth) sequential round trips even on fast SSDs
+- **Repo pattern**: the design doc specifies `Promise.all` fan-out; this pattern is used elsewhere in the codebase
+- **Scope**: best-fit -- change is inside `scan()`, no interface change
+- **Philosophy fit**: honors 'Compose with small pure functions' when fixed (scan becomes fan-out); violates 'Determinism over cleverness' if fan-out added without sort (see Issue E)
+
+**Evidence**: `src/application/use-cases/raw-workflow-file-scanner.ts` lines 23-35:
+```ts
+for (const entry of entries) {
+  const fullPath = path.join(currentDir, entry.name);
+  if (entry.isDirectory()) {
+    if (entry.name === 'examples') { continue; }
+    await scan(fullPath);  // sequential -- next dir waits for this one
+  } else if (...) { ... }
+}
+```
+
+---
+
+### Issue E: `findWorkflowJsonFiles` returns files in non-deterministic filesystem order
+
+**Summary:** The `files[]` array in `findWorkflowJsonFiles` is accumulated via sequential push
+with no final sort, so output order depends on `readdir` order, which varies by OS and filesystem.
+
+- **Tensions resolved**: names the non-determinism in the output
+- **Tensions accepted**: a sort step adds minor overhead (negligible at workflow file counts)
+- **Boundary**: return point of `findWorkflowJsonFiles`, after `await scan(baseDirReal)`
+- **Failure mode**: callers that process workflows in order may behave differently on macOS vs Linux CI; integration tests could have latent order-dependency bugs
+- **Repo pattern**: `request-workflow-reader.ts` already sorts entries: `const sortedEntries = [...entries].sort(...)` before iterating -- this is the established pattern
+- **Scope**: best-fit -- `files.sort()` before return
+- **Philosophy fit**: violates 'Determinism over cleverness'; fix restores it
+
+**Evidence**: `src/application/use-cases/raw-workflow-file-scanner.ts` line 37-39:
+```ts
+  await scan(baseDirReal);
+  return files;  // no sort -- order is readdir order (OS-dependent)
+}
+```
+vs `request-workflow-reader.ts` line 233:
+```ts
+const sortedEntries = [...entries].sort((a, b) => a.name.localeCompare(b.name));
+```
+
+---
+
+## Comparison and Recommendation
+
+| Issue | Severity | Category | Fix complexity |
+|---|---|---|---|
+| A: inspect_workflow unguarded | High | Robustness | Low (wrap in RA.fromPromise) |
+| B: phantom cache comment | Medium | Maintenance hazard | Trivial (comment update) |
+| C: statSync blocks event loop | Medium-high | Performance/correctness | Low (await fs.stat) |
+| D: sequential scan | Medium | Performance | Medium (Promise.all + sort) |
+| E: non-deterministic output | Low-medium | Correctness | Trivial (files.sort()) |
+
+All 5 are real, actionable, and distinct from the known 7.
+
+Fix priority: A first (crash exposure), then C (event-loop blocking), then D+E together
+(parallelization + sort are coupled), then B (editorial).
+
+---
+
+## Self-Critique
+
+**Strongest counter-argument against including all 5:**
+- Issue D and Issue E are both about `findWorkflowJsonFiles`, and the design doc (Item 1) already
+  covers them implicitly. But the known 7 issues don't name them explicitly -- they focus on the
+  walk in `request-workflow-reader.ts`. They belong in the new list.
+- Issue B (phantom cache comment) is 'just a comment' -- but it actively misrepresents the code
+  state, which is a maintenance correctness issue, not cosmetic.
+
+**Pivot conditions:**
+- If known issue #1 is interpreted to cover 'all call sites of createWorkflowReaderForRequest',
+  then Issue A would be a sub-item of #1, not a new issue. The known list's wording names only
+  `handleV2ListWorkflows` specifically.
+- If `findWorkflowJsonFiles` is not included in the perf fix scope, Issues D and E drop out.
+  But the design doc explicitly targets this function (Item 1).
+
+---
+
+## Open Questions
+
+1. Should Issue A be fixed as part of the existing issue #1 ticket, or as a separate item?
+2. Is `existsSync` at line 2 of raw-workflow-file-scanner.ts also used synchronously? (It is
+   imported but the actual uses should be audited -- it may introduce the same event-loop concern.)

package/docs/plans/perf-fixes-new-issues-review.md

@@ -0,0 +1,110 @@
+# Performance Fixes: New Issues Review Findings
+
+**Date:** 2026-04-07
+**Input:** `perf-fixes-new-issues-candidates.md`
+
+---
+
+## Tradeoff Review
+
+| Tradeoff | Verdict | Condition under which it fails |
+|---|---|---|
+| Issue E (non-deterministic order) is low severity today | Acceptable | Becomes medium once Issue D (parallelization) is implemented -- the two are coupled |
+| Issue D overlaps with design doc Item 1 | Acceptable | The design doc and the known-7 issue list are separate artifacts; Item 1 is not in the known list |
+
+No tradeoffs fail under review.
+
+---
+
+## Failure Mode Review
+
+| Failure Mode | Coverage | Highest Risk |
+|---|---|---|
+| Issue A: unhandled throw in inspect_workflow | No mitigation until fixed | YES -- production crash surface |
+| Issue C: event-loop stall on statSync | No mitigation until fixed | Medium-high under concurrent load |
+| Issue E: latent ordering bug after parallelization | No mitigation until fixed | Low today, medium once Issue D is fixed |
+
+**Highest-risk failure mode:** Issue A -- the only one that causes a production runtime crash
+(unhandled exception reaching the MCP transport layer).
+
+---
+
+## Runner-Up / Simpler Alternative Review
+
+No runner-up -- this is issue discovery, not competing design options. All 5 issues are distinct
+and minimal. No issue can be dropped without leaving a real defect or maintenance hazard.
+
+Issues D and E are coupled (parallelization without sorting makes non-determinism worse) and should
+be fixed together.
+
+---
+
+## Philosophy Alignment
+
+| Principle | Issue | Status |
+|---|---|---|
+| Errors are data | A: bare await in inspect_workflow | Violated -- throw not a data value |
+| Determinism over cleverness | E: unsorted file list | Violated -- same input, different output |
+| Document why not what | B: phantom cache comment | Violated -- describes nonexistent feature |
+| Async contract (no sync I/O in async) | C: statSync | Violated -- blocks event loop |
+| Functional/declarative | D: sequential for-of await | Tension -- sequential where fan-out is idiomatic |
+
+All violations are in the unfixed code. The issue list accurately names them.
+
+---
+
+## Findings
+
+### Red
+
+**Issue A: `handleV2InspectWorkflow` has an unguarded bare `await createWorkflowReaderForRequest(...)`**
+- `v2-workflow.ts` line 332: same unhandled-throw exposure as known issue #1 at line 193
+- `start.ts` line 364 is the correct reference: `RA.fromPromise(createWorkflowReaderForRequest(...), mapper)`
+- A `listRememberedRoots` error propagates as an unhandled exception to the MCP transport layer
+- Severity: production crash surface -- same as known issue #1, and equally urgent
+
+### Orange
+
+**Issue C: `statSync` at `raw-workflow-file-scanner.ts:95` blocks the Node.js event loop**
+- Synchronous I/O inside an async function; the `'fs'` sync import at line 2 is the entry point
+- Blocks all in-flight concurrent MCP requests during the stat call
+- Fix: `await fs.stat(filePath)` using the already-imported `fs/promises`
+- Secondary: audit `existsSync` (also imported from `'fs'` at line 2) for similar usage
+
+### Yellow
+
+**Issue D: Sequential `await scan(fullPath)` in `findWorkflowJsonFiles` (raw-workflow-file-scanner.ts:19-35)**
+- Each subdirectory is fully scanned before the next starts
+- Design doc (perf-fixes-design-candidates.md, Item 1) specifies `Promise.all` fan-out
+- Not named in any of the known 7 issues; it is a distinct item in a different file
+- Coupled with Issue E: must add `files.sort()` when parallelizing
+
+**Issue E: `findWorkflowJsonFiles` returns files in non-deterministic OS-dependent order**
+- `raw-workflow-file-scanner.ts:38`: `return files` without a preceding `files.sort()`
+- `FileWorkflowStorage` and `scanRawWorkflowFiles` both consume this output
+- Low risk today; escalates to medium the moment Issue D is fixed
+- Fix is one line: `files.sort()` before `return files`
+
+**Issue B: Test comment describes a walk cache that does not exist**
+- `perf-fixes.test.ts` lines 17-18: 'module-level walk cache (keyed on sorted root paths)'
+- No such cache exists in `request-workflow-reader.ts`
+- Future implementer reading the test might skip writing cache tests, believing they already exist
+- Fix: replace the phantom description with the actual reason (unique temp dirs prevent cross-test pollution)
+
+---
+
+## Recommended Revisions to the Candidates Document
+
+1. Elevate Issue A to the same urgency as known issue #1 -- they are identical in failure mode
+2. Add note to Issue C to audit `existsSync` usage (same file, same import line)
+3. Note that Issues D and E must be implemented together -- fixing D without E makes ordering worse
+
+---
+
+## Residual Concerns
+
+- **Issue A severity**: if the MCP transport layer already catches unhandled promise rejections
+  from handler functions and converts them to error responses, Issue A is mitigated at the
+  framework level. This should be verified before treating it as a crash vs. a degraded-response.
+- **Issue E completeness**: `FileWorkflowStorage.buildWorkflowIndex` also calls
+  `findWorkflowJsonFiles` -- order dependency there should be checked before declaring the fix safe.