Bound SignatureCache growth with a key-length cap and a bounded FIFO miss cache (APP-5431)

[warp-agent-staging]

Description

SignatureCache::get (crates/warp_completer/src/signatures/legacy/registry.rs) caches command lookups in memo_map::MemoMap, which is append-only by design (no eviction, size cap, or TTL — see its own doc comment).

The completer looks up an arbitrary token taken from the terminal input line on every keystroke/paste (Input::generate_autosuggestion_async → classify_command → parse_command → CommandRegistry::signature_from_tokens/signature_with_alias_expansion → SignatureCache::get). A correction to the linked Sentry analysis: the cache key is not the full buffer text, it's a single token (tokens.first(), or a later token via maybe_load_replacement_signature). The leak had two independent causes:

1. A single pathologically large token (e.g. pasting a large blob of text into the terminal input line) got lowercased, cloned, and permanently retained.
2. Every distinct token that ever missed the cache (not just huge ones) also got a permanent None entry — so the cache also grew without bound purely from the count of distinct short tokens seen over a session.

Linear: https://linear.app/warpdotdev/issue/APP-5431/unbounded-memory-growth-warp-completer-signaturecache-memomap-caches
Sentry: https://warpdotdev.sentry.io/issues/7259255054/

Fix

SignatureCache is split into two structures with different bounds and different eviction guarantees:

• signatures: MemoMap<String, Signature> — unchanged in shape. Only lookups that actually resolve to a signature are ever inserted. It stays append-only and keeps handing back Option<&Signature> borrowed from inside the map, which is what lets SignatureAtTokenIndex hold a &'a Signature across the parser with no API change. This bounds it by the number of distinct command names that can ever resolve to something — the fixed embedded corpus (1,167 top-level commands as of this writing) plus any explicitly register_signature-ed names (a handful of Warp CLI channel names) — rather than by every distinct token a user has ever typed or pasted.
• misses: MissCache — new. MissCache lives in its own module, crates/warp_completer/src/signatures/legacy/miss_cache.rs, beside registry.rs. It's a bounded, RwLock-guarded FIFO set (capacity MAX_CACHED_MISSES = 256, defined in that module) holding only the lowercased tokens that recently failed to resolve, no signatures. Because a lookup against it only ever returns a bool, no reference escapes it, so eviction is sound — unlike signatures, there's no outstanding borrow an eviction could invalidate. Internally it's a VecDeque (insertion order, for FIFO eviction) plus a HashSet (for O(1) membership checks), both behind one RwLock.
• Why a RwLock, not the Mutex from the prior revision: CommandRegistry::global_instance() is a single Arc shared across every terminal session/pane, each generating completions on its own background-thread-pool task, so this genuinely needs cross-thread synchronization — it's not effectively single-threaded. But the negative cache is inherently approximate: a false negative (a miss it forgot) costs one extra, cheap lookup_fn call, never a wrong answer — a much weaker bar than an LRU's guarantees require. Dropping strict LRU recency for plain FIFO eviction is what unlocks the RwLock: a hit against contains is now a pure read (shared read-lock, no mutation), and the write lock is only taken for a genuinely new miss. An LRU would need a write lock on every hit too (to move the entry to the front), which is exactly the shape of lock a RwLock doesn't help with — that's why a plain RwLock wasn't an option before this trade. The cost: a miss that's looked up again while the cache is full doesn't get a second life; it's evicted on schedule regardless. This also removes the lru crate as a dependency.
• Capacity (256) is picked to comfortably absorb a burst of misses from a single interaction — e.g. a user retrying a mistyped command letter-by-letter, where each partial token is a distinct miss — without holding onto misses for the life of a long session.
• For tokens longer than MAX_CACHEABLE_COMMAND_LEN (255 bytes — the common filesystem NAME_MAX), get now just returns None outright, before the lowercase allocation and before touching either cache. The previous revision instead fell back to a linear scan of signatures for this case, to keep an oversized register_signature-ed name retrievable. That scan is now gone: walking the full embedded corpus (recursively, including subcommands) plus the Warp CLI's own clap-derived command tree — the only other source of register_signature-ed names in production — the longest name found is 59 characters (a compound dig/dog subcommand name), well under the cap. test_all_known_signature_names_are_within_the_length_cap establishes and locks in that invariant; an artificially oversized register_signature-ed name is now unresolvable via lookup, a deliberate, tested tradeoff rather than a case that occurs today.

What the negative cache buys, honestly stated: a miss is already cheap to redo — lookup_fn probes the embedded, already-compiled signature corpus (rust-embed stores file contents statically and does a binary search — no filesystem I/O, no JSON parsing on a miss; JSON parsing only happens once we know there's a hit). So misses is a bounded convenience that saves a handful of redundant lookups for a token retried in quick succession (e.g. while a user is correcting a typo), not a fix for an expensive-recompute problem.

Alternatives considered and rejected

• A unified LRU over signatures itself, returning Option<Arc<Signature>> instead of Option<&Signature>. An earlier design for this revision, since it would let one bounded structure serve both hits and misses. Rejected by the requester: it changes SignatureCache::get's (and thus CommandRegistry::signature/signature_from_tokens/etc.'s) return type, which rev-locks callers like SignatureAtTokenIndex into holding an owned handle instead of a borrow — a bigger, more invasive change than this leak warrants.
• Cloning Signature on every lookup to allow eviction from a single LRU. Would turn a cheap reference return into a clone on every completion keystroke, a hot-path regression.
• A Mutex<lru::LruCache<..>> for the negative cache. The design in the immediately prior revision of this PR. Rejected by the requester in favor of the RwLock-guarded FIFO described above, once we'd confirmed the registry is genuinely multi-threaded (ruling out thread-local state) and that the cache's approximate nature makes strict LRU recency unnecessary.
• A fixed-size array of atomics holding token hashes, with no key strings retained. Considered for the negative cache but rejected: without the key, a hash collision would make a real, resolvable command permanently look like a known miss to that slot, silently dropping its completions. The HashSet-based design pays a little more memory for a set of ~256 short strings to avoid that failure mode entirely.
• Keying on the parsed command-name token only. This is effectively what already happens — the cache is already keyed on a single token, not the raw buffer (see the correction above).
• Rejecting long tokens outright instead of falling back to a scan. This is what the current revision does, now that the corpus-scan test establishes it's safe; see "Fix" above.

Other unbounded/user-input-keyed caches in the completer pipeline

Swept the rest of warp_completer for the same shape (an append-only or ever-growing cache keyed on user input):

• CommandRegistry::dynamic_completion_data (CaseInsensitiveHashMap) is built once from a fixed HashMap at CommandRegistry::new and never written after construction — confirmed not a second leak.
• No other MemoMap, HashMap, or similar cache keyed on raw user/terminal input was found elsewhere in crates/warp_completer.

Linked Issue

• N/A — tracked in Linear (APP-5431), not a GitHub issue.

Testing

MissCache now has its own module and companion test file, matching how registry.rs/registry_tests.rs are wired:

• crates/warp_completer/src/signatures/legacy/miss_cache.rs — the MissCache type, MissCacheEntries, and MAX_CACHED_MISSES.
• crates/warp_completer/src/signatures/legacy/miss_cache_tests.rs — direct unit tests against MissCache (no CommandRegistry involved): test_contains_reflects_recorded_misses, test_inserting_an_existing_entry_is_a_no_op, test_stops_growing_at_capacity, test_evicts_in_fifo_order_regardless_of_lookups (the FIFO-vs-LRU regression test, re-touching the oldest entry before overflow and asserting it's evicted anyway).

Unit tests remaining in crates/warp_completer/src/signatures/legacy/registry_tests.rs (these exercise SignatureCache/CommandRegistry behavior; the two oversized-token tests touch misses only to confirm the length guard never reaches it):

• test_all_known_signature_names_are_within_the_length_cap — walks every embedded signature (recursively, including subcommands) plus the Warp CLI's clap-derived command tree, asserting every name is within MAX_CACHEABLE_COMMAND_LEN. This is the invariant the oversized-token fast path in get depends on; if a future signature ever violates it, this test fails instead of that name silently becoming unresolvable.
• test_oversized_command_is_not_cached_and_resolves_to_none — an oversized, unregistered token resolves to None without growing either the positive or the negative cache.
• test_oversized_later_token_does_not_bypass_the_length_guard — an oversized later token (e.g. the argument to sudo, resolved via maybe_load_replacement_signature) takes the same length-guarded path as an oversized top-level token, via both signature_from_tokens and signature_with_alias_expansion.
• test_misses_are_never_cached_in_the_positive_cache — a normal-length command that never resolves to a signature never adds an entry to signatures, however many times it's looked up.
• test_ordinary_commands_still_resolve_and_are_cached — registered commands still resolve case-insensitively; repeated lookups hit the positive cache rather than growing it.
• test_registered_signature_longer_than_the_cap_is_unresolvable — a signature explicitly registered with an artificially oversized name is not retrievable via signature(), documenting the accepted tradeoff from removing the fallback scan.
• test_exe_suffix_is_trimmed_before_the_length_check (Windows-only) — a command name exactly at the cap resolves correctly when looked up with .exe appended, proving the trim happens before the length check.
• test_registered_commands_unaffected_by_oversized_lookups — CommandRegistry::registered_commands() is unaffected by oversized/negative lookups.

Validation run against crates/warp_completer:

• ./script/format — clean.

• cargo clippy -p warp_completer --all-targets --tests -- -D warnings — clean (default features, the legacy code path this PR touches).

• cargo clippy -p warp_completer --all-targets --all-features --tests -- -D warnings — fails with the same 5 pre-existing collapsible_if/let_and_return errors in completer/engine/argument/v2.rs, re-confirmed to reproduce identically on unmodified master; unrelated to this change.

• cargo nextest run -p warp_completer — 19 registry tests + 4 miss_cache tests pass. The same 25 pre-existing, unrelated failures reproduce identically on unmodified master (Tried to check FeatureFlag::CloudEnvironments before feature flags were initialized, in completer::describe/completer::engine/completer::suggest tests) — 149/174 total tests pass, matching the pre-existing baseline plus the new tests.

• cargo check -p warp_completer --features v2 — clean; the v2 registry implementation is a separate, untouched module.

• cargo check -p warp_terminal -p input_classifier -p warp_tui (dependents) — all build clean. SignatureCache's public-facing return types are unchanged (still Option<&Signature>).

• Removed lru as a dependency of warp_completer (no longer needed); MissCache is built on std::collections::{HashSet, VecDeque} and std::sync::RwLock only.

• Could not cross-compile-check the Windows-only test in this Linux sandbox (no Windows target/toolchain available); the ordering it tests (trim .exe before the length check) is unchanged from the previous revision.

• I have manually tested my changes locally (unit tests + the crate-scoped validation above; this is not a UI change so ./script/run manual testing doesn't apply).

Agent Mode

• Warp Agent Mode - This PR was created via Warp's AI Agent Mode

CHANGELOG-BUG-FIX: Fixed an unbounded memory leak in the terminal completions engine where large or unusual input (e.g. pasting a large blob of text) could permanently grow memory usage over a session.

Co-Authored-By: Warp agent@warp.dev

[acarl005]

trim down those comments as i request