galaxy/specs/APP-3945/PRODUCT.md

APP-3945: Channel-aware Warp home watching Product Spec

Summary

Warp should hot-reload the current channel's Warp-managed files without reacting to unrelated files under .warp*/worktrees. This includes continuing to reload settings.toml correctly on platforms where settings live under config_local_dir() instead of data_dir().

Problem

Warp currently relies on filesystem watching for several user-visible behaviors: reloading themes, workflows, launch configs, tab configs, Warp home MCP config, Warp home skills, and public settings from settings.toml. The watcher surface is easy to regress because Warp-managed files are split across different directories depending on platform and channel.

The specific failure modes this work addresses are:

• changes under .warp*/worktrees can produce false-positive updates for Warp home watchers
• a watcher rooted only at data_dir() can miss settings.toml on Linux and Windows, where config_local_dir() differs from data_dir()
• fresh installs or hermetic test environments can fail to watch missing directories unless Warp prepares those roots before registering the watcher

Goals

• Watch the current channel's Warp-managed directories through a single Warp-specific watcher model.
• Ignore filesystem activity under .warp*/worktrees so worktree contents do not trigger Warp home reload behavior.
• Continue reloading settings.toml when it changes on every supported platform, including platforms where settings live outside data_dir().
• Preserve existing hot-reload behavior for themes, workflows, launch configs, tab configs, Warp home MCP config, and Warp home skills.

Non-goals

• Changing where any Warp-managed file is stored.
• Changing the semantics of settings parsing, settings migration, or settings validation.
• Adding new user-facing UI for watcher state or diagnostics.
• Expanding watch coverage to arbitrary files outside Warp-managed directories.
• Changing the generic repository watcher APIs used for project repositories.

Figma / design references

Figma: none provided

User Experience

Watch scope

• Warp watches the current channel's Warp-owned filesystem roots through a single singleton watcher.
• data_dir() remains the source of truth for channel-scoped Warp home content such as themes, workflows, launch configs, tab configs, MCP config, and skills.
• config_local_dir() is also watched when it is a different directory from data_dir().
• When both path helpers resolve to the same directory, Warp behaves as before and does not create duplicate logical coverage.

Settings hot reload

• When settings.toml changes, Warp reloads public settings from disk and applies the new values to in-memory settings models.
• This behavior must work whether settings.toml lives in the same directory as the rest of Warp home files or in a separate config directory.
• Creating, modifying, renaming into place, or deleting settings.toml must continue to flow through the existing WarpConfigUpdateEvent::Settings path.

Worktree exclusion

• Files under .warp, .warp-dev, .warp-local, or equivalent channel-scoped Warp home directories that are nested inside worktrees/ must not trigger Warp home reload behavior.
• Editing files inside a cloned repository stored under .warp*/worktrees/... must not cause Warp to reload themes, workflows, tab configs, MCP config, skills, or settings.

Channel awareness

• Warp only reacts to files under the active channel's directories.
• A stable or dev install should not reload in response to files written into another channel's Warp home.

Fresh-install and test-environment behavior

• If a watched Warp-owned root directory does not exist yet, Warp should create it during startup/setup before registering the watcher.
• Missing directories must not silently disable hot reload for the rest of the session.

No regressions for existing consumers

• Editing a theme file in Warp home still updates the available theme set.
• Editing workflows, launch configs, or tab configs in Warp home still refreshes those objects.
• Editing Warp home MCP config still updates file-based MCP servers.
• Editing Warp home skills still refreshes Warp-provided skills.

Success Criteria

• settings.toml hot reload works on macOS, Linux, and Windows.
• Worktree activity under .warp*/worktrees no longer triggers Warp home reloads.
• Themes, workflows, launch configs, tab configs, Warp MCP config, and Warp skills continue to hot reload from the current channel's Warp home.
• Warp prepares missing watch roots before attempting to register watchers.
• The watcher architecture remains centralized behind a Warp-specific singleton instead of reintroducing separate ad hoc watchers for individual consumers.

Validation

• Unit-test the watcher filtering behavior so updates outside the kept prefix are excluded and cross-boundary moves are handled correctly.
• Run the end-to-end settings hot-reload integration test that edits settings.toml multiple times and verifies the in-memory settings model changes after each write.
• Manually or through existing automated coverage, verify that editing Warp home themes, skills, and MCP config still produces the expected reload behavior.
• Confirm via code review that only data_dir() receives the worktrees exclusion and config_local_dir() remains unfiltered.

Open questions

• None currently.