refactor(tui): scope data lifecycle to the active location #36185

Problem

The V2 TUI has two different location concepts that are not connected:

• defaultLocation is resolved from the TUI startup directory and drives bootstrap plus every location-optional data getter.
• LocationProvider follows the active Home or Session route, but it is only an accessor. It does not hydrate, invalidate, or reconcile that location's cached data.

As a result, some session UI explicitly reads the route location while other code silently reads the startup location. Navigating to a session at another location does not bootstrap that location's agents, commands, integrations, MCP servers, models, providers, references, skills, or shells.

This is broader than the stale shell count tracked in #35816.

Observed Failure

On 0.0.0-next-15234, session ses_0b8ba14adffeC6p87v57JF1FSf showed 2 shells in the footer while the Shell tab showed no commands.

The timeline exposed two independent problems:

1. The footer read the session's life-hub shell cache, while the Shell tab read the startup/default cache.
2. After the service upgrade/restart, the new server reported no shells, but reconnect refreshed shells only for defaultLocation, leaving the non-default life-hub cache stale.

The restart also exposed the inverse performance problem. Bootstrap discovered historical session locations and eagerly refreshed global forms across at least eight location graphs. Location boot took 7-21 seconds for several projects, watchers were still starting around 25 seconds, and the service reached roughly 53% CPU and 3.1 GB RSS during the reconnect herd.

Current Lifecycle

DataProvider initializes defaultLocation from process.cwd() and changes it only during no-argument bootstrap location resolution.

Every initial SSE connection and reconnect emits server.connected. DataProvider responds by refreshing the default location's:

• sessions
• permissions and forms
• agents and commands
• integrations and MCP
• models and providers
• references and skills
• shells

It then refreshes only global forms for every distinct non-default location found in the loaded session list.

Session route activation separately refreshes session info, messages, permissions, forms, and global forms. It does not hydrate the location-scoped resources above. session.moved changes the reactive LocationProvider, but the route-ID activation effect does not rerun, so project/editor side effects and cached resources remain attached to the old location.

Confirmed Bugs

• Non-default session routes read uninitialized location caches.
• Agent/model state can come from the startup location and be submitted to a session at another location.
• The Shell tab lists the default location even though shell termination uses the active route location.
• Prompt autocomplete reads default-location references and agents.
• Model, integration, MCP, status, and provider-connectivity views frequently read the default location.
• reference.updated ignores event.location and refreshes default references.
• Reconnect leaves non-default agents, models, commands, references, skills, integrations, MCP, and shells stale.
• Default-location whole-map reconciliation can remove a non-default session's pending permissions/forms without restoring them.
• A reconnect arriving during an existing bootstrap can be coalesced into the old bootstrap without scheduling a fresh pass.
• Snapshot responses can overwrite newer event projections. For shells, an older /api/shell response can resurrect a process already removed by shell.exited.
• Remote/server-attached startup can split the implicit default between the local TUI cwd and the server/client default.

Desired Model

Make location activation a real cache lifecycle seam.

A location scope should:

• be keyed by canonical { directory, workspaceID }
• retain its canonical location rather than relying only on a serialized record key
• lazily bootstrap when Home or a Session route acquires it
• expose bound resource selectors so descendants cannot silently fall back to another location
• receive event updates by event.location
• become stale when the event stream disconnects
• refresh only active or explicitly pinned scopes after reconnect
• refresh before reuse when returning to an inactive cached scope
• be evictable after it is inactive

Conceptually:

const location = data.location.scope(session.location)

location.agent.list()
location.model.list()
location.shell.list()

defaultLocation should mean the Home/new-session location only. It should not be the implicit location for code rendered under an active Session location.

The existing App global-sync implementation is a useful precedent: lazy directory child stores, bootstrap-on-access, reconnect queues, pinning, and eviction. The TUI likely needs a smaller version of that module rather than shell-specific provenance fields.

Reconnect Semantics

On disconnect:

• Mark event-backed inventories stale.
• Never continue presenting an old shell inventory as authoritative.
• Preserve cached durable/config data only with an explicit stale state.

On server.connected:

• Refresh the root/default scope only if Home needs it.
• Refresh currently active/pinned location scopes.
• Do not bootstrap every location represented by recent session history.

For resources populated by both snapshots and live events, define ordering rather than relying on last-write-wins. A refresh should capture a connection epoch or mutation revision and discard/retry if a newer lifecycle event arrives before the snapshot is applied. If generation machinery remains intentionally excluded from DataProvider, the server inventory protocol needs an equivalent snapshot watermark.

Route Semantics

Entering location B should:

1. Acquire B's location scope.
2. Bootstrap B if absent or stale.
3. Render all descendants against B's bound data.
4. Release the previous scope after navigation.

Moving the current session from A to B should trigger the same lifecycle, including project workspace and editor reconnection.

Returning to A may use cached data while revalidating for durable/config resources, but ephemeral process inventory must not be shown as current until reconciled.

Suggested Sequence

1. Introduce a generic active-location scope/lease in the TUI data layer.
2. Move location bootstrap from global default bootstrap into scope activation.
3. Bind Session descendants to scoped selectors and remove implicit default fallbacks.
4. Make session movement rerun location activation side effects.
5. Reconcile active scopes after reconnect and stop eagerly booting historical locations.
6. Add snapshot/event ordering for ephemeral inventories.
7. Add inactive-scope eviction if cache growth warrants it.

Acceptance Criteria

• Opening an existing session at a non-default location hydrates all location-scoped resources before they are treated as ready.
• Switching locations cannot display or submit agents/models from the previous/default location.
• Session movement updates data scope, project workspace, and editor directory.
• Reconnect cannot leave stale shell counts or erase non-default pending interactions.
• The Shell tab and footer read the same active location.
• Location-scoped update events refresh the event's location.
• Restart cost scales with active/pinned locations, not all locations in recent session history.
• Tests cover first navigation, route switching, session movement, transient reconnect, service replacement, and a snapshot/event race.

Open Decisions

• Should location bootstrap block route readiness, or expose partial/stale states while resources load?
• Which resources may use stale-while-revalidate, and which must be hidden until authoritative?
• Should the cache support multiple simultaneously pinned locations now, or begin with one active route location?
• Should snapshot/event ordering be solved client-side with epochs/revisions or server-side with inventory watermarks?
• Shell footer semantics remain a separate decision in bug(tui): shell footer count can become stale #35816: all shell-tool processes versus explicitly backgrounded jobs.

Related

• bug(tui): shell footer count can become stale #35816
• fix(tui): prevent stale shell counts #35814
• fix(tui): reconcile shells after reconnect #36184