# When a button feels slow: trace the wait

> When a button feels slow: trace the wait

Repository: syntaxskills/muxmap · Category: Terminals and processes · Status: Active

Keywords: terminal, discovery, race condition, session management

## When to use this lesson

- A button press or action feels unresponsive or delayed.
- The terminal session appears to close or stop unexpectedly after creation.
- Users report that new terminals are not functioning as expected.

## What happened

In MuxMap, there was a race condition where workspace polling could stop a new terminal session if discovery was in progress. This led to incorrect session states being reported, causing the terminal to appear unresponsive or to close unexpectedly. The issue was particularly noticeable when creating new terminals while workspace polling was active.

## Diagnosis and approach

The terminal session management system had a race condition between workspace polling and new terminal creation. Discovery snapshots could become stale if a new terminal was created while a discovery was in progress, leading to incorrect session states being reported. The root cause was that discovery snapshots were not properly invalidated when runtime states changed, allowing obsolete data to persist.

## What did not work

No unsuccessful experiments are documented in the supplied evidence.

## What changed

The solution involved modifying the discovery process to use a fresh snapshot when reconciling sessions. This was achieved by introducing a revision counter that increments whenever the runtime state changes, ensuring that any in-flight discovery operations detect and handle these changes. The `freshDiscoverySnapshot` function was added to fetch the most up-to-date discovery data, and the `invalidate` method was updated to increment the revision counter, forcing any ongoing discovery to restart with the new state.

## How to verify the improvement

1. Create a new terminal session while workspace polling is active. 2. Monitor the session state to ensure it remains running and is not incorrectly marked as stopped. 3. Verify that the discovery process uses the most up-to-date snapshot to avoid stale data. 4. Check that the revision counter correctly increments when runtime state changes, forcing any in-flight discovery to restart with the new state.

## What to do next time

When managing terminal sessions with discovery mechanisms, ensure that discovery snapshots are always fresh and reflect the current runtime state. Any changes to the runtime must invalidate in-flight discovery to prevent stale data from being used. Use revision counters to detect and handle concurrent updates correctly.

## Limits and exceptions

This solution applies to systems where discovery processes can be interrupted or updated while in progress. It is particularly relevant for terminal session managers that need to maintain accurate state across multiple asynchronous operations. Other systems with similar concurrency challenges may benefit from this approach, but the specific implementation details will vary based on the architecture.

## Commit evidence

- [syntaxskills/muxmap@ccf900a](https://github.com/syntaxskills/muxmap/commit/ccf900aa92890671fb7c513e095e1e37d01da21a): Added attach progress, lazy loading feedback, explicit connection readiness, and input gating.
- [syntaxskills/muxmap@69c72df](https://github.com/syntaxskills/muxmap/commit/69c72df320e25de351d6f4ba578b940ba47478f5): Opened terminals from the returned session immediately and rejected older workspace responses with a revision guard.
- [syntaxskills/muxmap@fcbe7a4](https://github.com/syntaxskills/muxmap/commit/fcbe7a43f30aec5d39569bc6f9e16f18454d798e): Reconciliation can mark sessions stopped, so it must not use an invalidated snapshot.