feat: breadcrumb navigation, subworkflow isolation, and stop reliability

[PolyphonyRequiem]

Summary

Adds full subworkflow awareness to the per-run web dashboard with breadcrumb navigation, fixes node status pollution from repeated subworkflow runs, and fixes the Stop button not working during subworkflows.

Changes

State Pollution Fix

• Added wfDepth counter to the Zustand workflow store — only depth-0 workflow_started initializes root context
• Each subworkflow invocation gets an isolated SubworkflowContext with its own nodes/routes/agents/groupProgress maps
• Repeated runs of the same subworkflow no longer share state (no more green/blue node bleed)

Subworkflow Event Handling

• Added TypeScript types for subworkflow_started, subworkflow_completed, subworkflow_failed
• Event handlers create/update child contexts and route events via activeTarget() helper

Breadcrumb Navigation

• BreadcrumbBar component shows the context stack above the graph
• Click any breadcrumb to navigate to that context level
• Double-click a workflow agent node to dive into its subworkflow graph
• getViewedContext() + useViewed*() hooks provide stable, memoized context data

Subworkflow Node Visual

• New WorkflowNode React Flow node type with dashed border and Layers icon
• SubworkflowDetail panel lists subworkflow runs with status/cost, click to navigate

Stop Button Reliability (Engine Fix)

• _check_interrupt(): in subworkflows (depth > 0), raises InterruptError instead of silently consuming the interrupt event — unwinds the child engine back to the parent
• _handle_web_pause(): in subworkflows, also watches interrupt_event so Stop-while-paused works without requiring Resume first

Context-Aware Rendering

• All graph node components read from useViewed*() hooks instead of root state
• Detail panels resolve nodes from the viewed context

Testing

• Zero new TypeScript errors (all tsc errors are pre-existing)
• Verified on live dashboard instance at localhost:60108

[codecov-commenter]

Codecov Report

❌ Patch coverage is 90.19608% with 5 lines in your changes missing coverage. Please review.
⚠️ Please upload report for BASE (main@af2bbec). Learn more about missing BASE report.

Files with missing lines	Patch %	Lines
src/conductor/web/server.py	86.48%	5 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #113   +/-   ##
=======================================
  Coverage        ?   85.59%           
=======================================
  Files           ?       53           
  Lines           ?     7629           
  Branches        ?        0           
=======================================
  Hits            ?     6530           
  Misses          ?     1099           
  Partials        ?        0           

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[PolyphonyRequiem]

Follow-up: extending this PR with the recursive-gate-navigation fix

Heads up — I'm pushing an additional commit to this branch that fixes two related issues in this same surface area, plus the engine plumbing they need:

Symptoms being fixed

1. Gates inside nested sub-workflows are unreachable from the dashboard. The view doesn't follow the active context when a sub-workflow spawns deeper, so a human_gate inside a child workflow appears as already-selected/inactive in the breadcrumb tree until the user manually navigates to it.
2. Cannot drill into sub-workflow contexts from the parent agent node detail panel reliably under concurrency.

Root cause

The store today resolves "which sub-workflow context owns this event" by reading state.activeContextPath, then mutates that path on every subworkflow_started. That works for strictly serial nesting but breaks under any concurrency, and means the view cursor (what the user is looking at) and the active cursor (what the engine is currently executing) are conflated. There's no engine-side identity for a sub-workflow context, so the frontend has to infer it.

Approach

Move the source of truth for sub-workflow identity to the engine:

• Each WorkflowEngine carries _dashboard_context_path: list[str] — the slot-key path identifying its own position in the recursive sub-workflow tree. Root engine = []. Child engine spawned by _execute_subworkflow(agent, ..., slot_key=…) gets [*parent_path, slot_key].
• _emit auto-stamps subworkflow_path on every event a sub-engine produces. The dashboard uses this to route per-iteration agent events to the correct context (essential once concurrency is in play — see feat(composition): allow sub-workflows in for_each groups (#102) #110 below).
• subworkflow_started / _completed / _failed for sequential sub-workflows now include parent_path: list[str] and slot_key: str so the frontend never has to guess parentage from activeContextPath.
• Frontend store: subworkflow_* and workflow_* handlers resolve the owning context strictly from engine-supplied paths (via a new resolveSlotPath helper). activeTarget consults subworkflow_path on the event payload before falling back to activeContextPath. Handlers gracefully fall back to legacy behavior when these new fields are absent — no regression for events from older engine versions.
• viewContextPath sticks to the live edge when the user hasn't navigated away (deep-equal check before the engine advances activeContextPath), so newly-spawned gates are reachable without manual breadcrumb clicks. If the user has manually navigated, their view is left alone.
• SubworkflowDetail now navigates by ctx.slotKey (stable across reorders) instead of (agent_name, iteration).
• New engine test: TestSubWorkflowDashboardPath verifies sequential subworkflow_started/_completed carry parent_path/slot_key and that child workflow_completed is auto-stamped with subworkflow_path.

Relationship to #110 (feat/for-each-workflows)

The "concurrency" half of this fix is mostly latent until #110 lands — sequential sub-workflows can't have concurrent siblings under one parent. But the frontend handlers and the engine infra are both needed for #110's for_each-of-workflow path to render correctly in the dashboard (otherwise concurrent for_each iterations of a sub-workflow stack as descendants of one another instead of laying out as siblings of the parent group).

I'm pushing a no-op-until-this-lands companion commit to #110 that adds the for_each-side parent_path/slot_key/item_key/iteration emit fields and threads slot_key into _execute_subworkflow_with_inputs. It uses getattr for _dashboard_context_path so it doesn't blow up on #110 alone. Once both PRs merge to main, the wiring is end-to-end.

Order of merge between #110 and #113 doesn't matter — both PRs are independently safe.

[PolyphonyRequiem]

Pushed 34de287 (cherry-picked from local main, then frontend assets rebuilt for that bundle hash). Force-push from fork landed cleanly.

Status:

• Gate runs: only license/cla shows on this head SHA. The branch is currently mergeStateStatus: DIRTY / behind_by: 5 against main, so the upstream CI workflows do not appear to have been triggered for this push. A rebase (or a maintainer "approve workflow runs" click) should kick them.
• Companion PR feat(composition): allow sub-workflows in for_each groups (#102) #110 (feat/for-each-workflows) was pushed in parallel with the for_each-side companion changes and is fully green (7/7 checks). The two PRs are independently safe to land in either order — see the design discussion comment above.

[PolyphonyRequiem]

Resolved the conflicts by rebasing feat/web-breadcrumb-navigation onto microsoft/conductor:main (was 5 behind, including #109's _execute_subworkflow_with_inputs and #107's run_context/metadata field).

Conflict resolution:

• WorkflowEngine.__init__: kept both new kwargs (run_context, _dashboard_context_path) and both initialization blocks (system metadata + dashboard context path) — the two are orthogonal.
• tests/test_engine/test_subworkflow.py: kept upstream's TestSubWorkflowInputMapping class as-is, appended TestSubWorkflowDashboardPath after it.

Rebased head is 5d4bb86. All 7 gates green.

[jrob5756]

Very cool change. Made a few comments. Then we can merge.

[jrob5756]

Concurrent for-each-of-workflow context corruption.

This handler routes via the global state.activeContextPath instead of the engine-stamped data.subworkflow_path. The PR went to lengths to add subworkflow_path auto-stamping in _emit (workflow.py:430-434) and uses it in workflow_completed (line 1293) and workflow_failed (line 1331) — workflow_started is the missing one.

Reproduction with concurrent for_each-of-workflow:

1. Iteration A emits subworkflow_started → activeContextPath=[0]
2. Iteration B emits subworkflow_started → activeContextPath=[1]
3. Iteration A's child engine emits workflow_started (carrying subworkflow_path=[A_slot]) → resolved to activeContextPath=[1] → A's graph/agents populate B's context.

Fix: resolve via subworkflow_path first, falling back to activeContextPath:

const ctx = (data.subworkflow_path !== undefined
  ? resolveSlotPath(state.subworkflowContexts, data.subworkflow_path as string[])?.ctx
  : null)
  ?? resolveContext(state.subworkflowContexts, state.activeContextPath);

[PolyphonyRequiem]

Fixed in d27109d. Adopted your suggested resolution pattern (subworkflow_path with activeContextPath fallback) and added subworkflow_path?: string[] to WorkflowStartedData so the resolver can read it without a cast.

Also added a regression test in test_subworkflow.py::TestSubWorkflowDashboardPath::test_concurrent_for_each_subworkflow_emits_distinct_slot_keys that exercises max_concurrent=3 (the existing for_each test only covered the sequential max_concurrent=1 case).

[jrob5756]

Silent fallback to root + activeContextPath corruption on slot-resolution miss.

resolved?.indexPath ?? [] silently falls back to the root context ([]), and state.activeContextPath = parentIndexPath later in the handler then unconditionally overwrites the active path. If resolveSlotPath returns null (e.g., event arrives before its sibling subworkflow_started, or any path inconsistency), the code:

1. Targets state.nodes (root) and stamps status: 'completed' on a same-named root agent that has nothing to do with the subworkflow.
2. Resets activeContextPath to [], breaking subsequent sibling routing.

Compare to subworkflow_started at line 1364 which correctly does if (!resolved) return;. Mirror that here:

if (data.parent_path !== undefined) {
  const resolved = resolveSlotPath(state.subworkflowContexts, data.parent_path);
  if (!resolved) return;
  parentIndexPath = resolved.indexPath;
} else {
  parentIndexPath = state.activeContextPath;
}

The identical bug exists in subworkflow_failed at line 1458 — please fix both.

[PolyphonyRequiem]

Fixed in 37d856d. Mirrored the if (!resolved) return; guard from subworkflow_started (line 1364) in both subworkflow_completed (line 1419) and subworkflow_failed (line 1458). On a slot-resolution miss, both handlers now return early instead of silently falling back to root and clobbering activeContextPath.

[jrob5756]

Headline feature is untested.

This new if self._subworkflow_depth > 0: raise InterruptError(...) branch — and the matching new stop_task logic in _handle_web_pause (lines 1077-1110) — have zero test coverage. Every test in TestCheckInterrupt (tests/test_engine/test_workflow_interrupt.py:572-658) constructs an engine with _subworkflow_depth=0, so this branch is dead code under tests. You could delete lines 969-970 and all 45 tests in the suite would still pass.

Since "Stop button reliability during subworkflows" is a headline feature of this PR, please add at minimum:

1. test_check_interrupt_raises_in_subworkflow — engine with _subworkflow_depth=1 and _web_dashboard set; assert InterruptError is raised.
2. test_handle_web_pause_stop_event_in_subworkflow — pause a child engine, set _interrupt_event, assert InterruptError.
3. test_nested_subworkflow_path_accumulates — depth ≥ 2; assert subworkflow_path chains correctly across multiple levels.
4. test_subworkflow_failed_event_carries_parent_path_and_slot_key — make the child raise; assert the failed event payload (currently only the success path is asserted at tests/test_engine/test_subworkflow.py:1014-1015).
5. A for_each-of-workflow test asserting distinct slot_key per iteration — the existing test only covers the trivial sequential case (slot_key == agent.name).

[PolyphonyRequiem]

Fixed in fef6b36. Added the test cases you specified (and one bonus):

• TestCheckInterruptSubworkflow::test_check_interrupt_raises_in_subworkflow - engine with _subworkflow_depth=1 and _web_dashboard set; asserts InterruptError is raised and interrupt_event is cleared.
• TestCheckInterruptSubworkflow::test_check_interrupt_consumed_silently_at_root - regression guard for the root-depth silent-consume branch.
• TestHandleWebPauseSubworkflow::test_handle_web_pause_stop_event_in_subworkflow - pauses a child engine, sets _interrupt_event mid-pause, asserts InterruptError.
• TestHandleWebPauseSubworkflow::test_handle_web_pause_root_ignores_interrupt_event - documents the intentional root-vs-subworkflow asymmetry as an executable spec.
• TestSubWorkflowDashboardPath::test_subworkflow_failed_event_carries_parent_path_and_slot_key - child raises, asserts the failed event payload (agent_name, parent_path, slot_key, error_type, message).
• TestSubWorkflowDashboardPath::test_nested_subworkflow_path_accumulates - depth 2 (parent -> mid -> leaf), asserts subworkflow_path chains correctly across both levels and that the root engine still emits workflow_completed without a stamp.
• TestSubWorkflowDashboardPath::test_concurrent_for_each_subworkflow_emits_distinct_slot_keys - your point Idle recovery: cumulative counter fails long-running agents — add per-workflow config and reset-on-progress #5. The existing test_for_each_subworkflow_emits_distinct_slot_keys already covers slot-key uniqueness for for_each-of-workflow, but it ran with max_concurrent=1 so iterations were sequential. The new test uses max_concurrent=3 so iterations actually overlap, proving uniqueness is not an artifact of serial execution.

Engine suite: 53 passed (was 46), one pre-existing Windows path failure in test_event_log.py is unrelated.

[jrob5756]

Pause+Stop UX diverges between root and subworkflow.

Pre-clearing interrupt_event here means a quick double-click of Stop (where the second click lands before partial output reaches _handle_web_pause) silently discards the second signal. Behavior also differs from root: at root, a second Stop while paused is ignored until Resume (only Kill works); here, the second Stop is honored — but only if it arrives after the pause is established.

At minimum, add a code comment explaining the intentional asymmetry. Ideally, document the divergence in the dashboard UX docs (or align behavior between root and subworkflow).

[PolyphonyRequiem]

Fixed in 1c3d199 with an inline comment in _handle_web_pause covering all three points:

1. Why root depth deliberately omits the interrupt_event subscription (pause exits only on Resume or Kill).
2. Why subworkflow depth subscribes to it (so Stop unwinds the child engine without requiring Resume first).
3. The tiny clear()/create_task() race window where a Stop click can be silently discarded, and the trade-off vs. carrying a stale Stop signal across pause cycles.

Also added TestHandleWebPauseSubworkflow::test_handle_web_pause_root_ignores_interrupt_event (in fef6b36) as an executable spec for the asymmetry, so the next person who tries to "fix" it gets a failing test.

Aligning behavior between root and subworkflow Stop semantics feels out of scope for this PR - happy to file a follow-up if you want them unified one way or the other.

[PolyphonyRequiem]

@jrob5756 good catch — confirmed and fixed.

what happened: i did the review-fix work on a local branch from another machine, then a force-push of unrelated work (6fb6e93 viewport auto-fit, etc.) from this machine landed on top of 9c1abed and overwrote the chain. the fix commits stayed reachable in my local reflog but never made it back to origin.

remediation (no force-push):

• f374a19 — fix(web): bail on slot-resolution miss in subworkflow_completed/failed (your finding Support file path as an input #2)
• 75e2142 — test(engine): cover subworkflow stop/interrupt and dashboard event payloads (53 tests, all pass)
• 15afe2c — docs(engine): document root-vs-subworkflow pause/stop asymmetry
• e1212ed — build: rebuild static assets so the bundle reflects the slot-resolution fix

cherry-picked on top of current origin and fast-forwarded — no force-push, your in-flight reviews stay intact.

re finding #1 (workflow_started subworkflow_path routing): 22f1988 already on the branch is functionally equivalent to my orphaned d27109d (same fix to the same line range, just inline-cast vs typed-field). no need to re-cherry-pick.

PR head is now e1212ed. apologies for the noise — the cross-machine state had me chasing a ghost.

[jrob5756]

All critical and important fixes verified at b2eb97f:

• ✅ C1: workflow_started routes via subworkflow_path with activeContextPath fallback
• ✅ I1: bail-on-resolution-miss guards added in both subworkflow_completed and subworkflow_failed
• ✅ I2: 9 new tests in TestCheckInterruptSubworkflow / TestHandleWebPauseSubworkflow / TestSubWorkflowDashboardPath cover the depth>0 interrupt branch, stop-while-paused, distinct slot_keys per for_each iteration, nested path accumulation, and failed event payload — all passing
• ✅ S1: comprehensive root-vs-subworkflow asymmetry comment in _handle_web_pause

Carrying I3 (server.py over-broad AssertionError suppression on Windows shutdown) and S2/S3 (comment/docstring nits) into a follow-up issue rather than blocking on them. Nice work, ship it.