terminal-ai-helper 2.3.1 → 2.3.3

package/VERSION

@@ -1 +1 @@
-2.3.1
+2.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminal-ai-helper",
-  "version": "2.3.1",
+  "version": "2.3.3",
   "description": "The terminal that knows your next command Bash/Zsh suggestions that learn from your own history Offline and private with no account required",
   "license": "MIT",
   "repository": {

package/plugins/bash/keys.bash

@@ -15,6 +15,12 @@ _tai_prompt() {
   raw="${raw#"${raw%%[![:space:]]*}"}"       # drop the leading indent
   while [[ "$raw" == [0-9]* ]]; do raw="${raw#?}"; done   # drop the history number
   last_cmd="${raw#"${raw%%[![:space:]]*}"}"  # drop the space after it
+  # A completion's own space rides the line into the history (`nano ` after a
+  # menu choice), and the store strips it — but this shell's next prediction
+  # looks the last command up in the sequence table by its exact text, and the
+  # table's keys are the stored, stripped rows. Trim here, once per command,
+  # so `nano ` predicts what followed `nano` and records the same row either way.
+  while [[ "$last_cmd" == *[[:space:]] ]]; do last_cmd="${last_cmd%?}"; done
   if [[ -n "$last_cmd" && "$last_cmd" != "$_TAI_LAST" ]]; then
     _TAI_LAST="$last_cmd"
     # The unit cache pre-loads itself in the background after a command that
@@ -247,12 +253,25 @@ _tai_complete() {
 # by both loops above — once as the file that is here, once as the line the
 # history holds — and COMPREPLY holding it twice makes readline print it twice.
 _tai_reply() {
-  local c
+  local c x
   # A learned line carrying raw control bytes is not a completion it is this
   # plugin's promise to never paint: what it would write is escape bytes.
   [[ "$1" =~ [[:cntrl:]] ]] && return 0
-  for c in "${COMPREPLY[@]}"; do [[ "$c" == "$1" ]] && return 0; done
-  COMPREPLY+=("$1")
+  c="$1"
+  # A completion that leaves the line one bare word is a command waiting for
+  # its arguments, and readline's own completion would have written the space
+  # between them (`cat tzz_solo `). `-o nospace` took that append away from
+  # every entry so a directory's slash could stand alone, so the entries that
+  # want the space carry it — measured on a real shell, a match holding a
+  # trailing space is inserted verbatim, and the common prefix of matches that
+  # disagree past the space is the prefix alone. Three shapes carry none: a
+  # directory's slash, which is the path still being typed; a whole learned
+  # line, which is the line the user ran, and whose space would ride the next
+  # Enter into the history as a row of its own; and a name that already holds
+  # a space, which is more than one shell word already.
+  if [[ -n "$c" && "$c" != */ && "$c" != *[[:space:]]* ]]; then c="$c "; fi
+  for x in "${COMPREPLY[@]}"; do [[ "$x" == "$c" ]] && return 0; done
+  COMPREPLY+=("$c")
 }
 complete -o nospace -F _tai_complete tai 2>/dev/null
 # -o default is what makes Tab fall back to readline's own filename completion

package/plugins/zsh/menu.zsh

@@ -769,6 +769,24 @@ _tai_menu_commit() {
   # slash from truncating what gets written.
   (( ${_TAI_MENU_Q[_TAI_MENU_IDX]} )) && { _tai_quote "$entry"; entry="$_TAI_QUOTED" }
   BUFFER="${BUFFER[1,$(( _TAI_MENU_FROM - 1 ))]}$entry${BUFFER[_TAI_MENU_TO + 1,-1]}"
+  # A completion that leaves the line one bare word is a command waiting for its
+  # arguments, and the space between them is written for the user — every
+  # shell's own completion does this, and readline's half of this plugin always
+  # did (`cat tzz_solo `). The report: choosing `nano` out of the menu put
+  # `nano` in the line, and the user typed the space by hand, once per line,
+  # every time. Three shapes write nothing after them: a directory's slash,
+  # which is the path still being typed; a whole learned line, which is the
+  # line the user ran, and whose space would ride the next Enter into the
+  # history as a row of its own; and a name that already holds a space, whose
+  # quoting is the shell word it is.
+  [[ "$entry" != */ && "$entry" != *[[:space:]]* ]] && BUFFER+=" "
+  # What the commit wrote is the line the user took. Without this, the space a
+  # bare-word commit writes is one deletion from the learned line itself, and
+  # the loose glimpse answered the very next redraw with the line just taken —
+  # `cd tzz_dir ` re-offering `cd tzz_dir` from under the cursor. The same
+  # dismiss an Up from a glimpse sets: while the text stands, the list does not
+  # spring back, and the next keystroke re-arms it.
+  _TAI_MENU_DISMISS="$BUFFER"
   CURSOR=${#BUFFER}
   _tai_menu_close
 }

package/plugins/zsh/widgets.zsh

@@ -762,6 +762,12 @@ _tai_preexec() {
   # resolved in the background write instead, which also means the repo, branch
   # and cwd all describe the same moment. bash has always done it this way.
   _TAI_CMD="$1"
+  # A completion's own space rides the line into preexec (`nano ` after a menu
+  # choice), and the store strips it on the way in — but this shell's next
+  # prediction looks the last command up in the sequence table by its exact
+  # text, and the table's keys are the stored, stripped rows. Trim here, once
+  # per command, so `nano ` predicts what followed `nano`.
+  while [[ "$_TAI_CMD" == *[[:space:]] ]]; do _TAI_CMD="${_TAI_CMD%?}"; done
   # The directory the command was *run from*. A prompt-time $PWD comes after the
   # command, so for `cd src` the recorded origin was the destination — and the
   # path-liveness check judged the cd's argument against the place it had just

package/readme.md

@@ -38,7 +38,7 @@ exec zsh
 ✓ bash installed
 
   1. Type a few letters — tai finishes the command in grey. → takes it.
-  2. Tab opens a menu of what fits. Enter picks; a second Enter runs.
+  2. Tab opens a menu of what fits. Enter picks, space after the command included; a second Enter runs.
   3. It learns from your history — offline, private, no account.
 
   Try it now: type "cd " and watch the grey.

package/tai/cli.py

@@ -381,14 +381,19 @@ def _auto_maintain(total: int, newest_ts: int = 0) -> None:
 def _rebuild_when_stale(newest_ts: int | None = None) -> None:
     import time
 
-    from tai.index import index_path
-    from tai.maintenance import _rebuild_quietly
-
-    idx = index_path()
-    if not idx.exists():
+    from tai.paths import index_location
+
+    # The index is named as a plain string and stat'd with os: importing
+    # tai.index to ask `Path.exists` pulled the engine, the knowledge loader
+    # and pathlib into every record and flush for one stat that usually says
+    # "fresh enough". The rebuild imports are inside the two branches that
+    # rebuild, so a debounce hit is one stat and one comparison.
+    idx = index_location()
+    if not os.path.exists(idx):
+        from tai.maintenance import _rebuild_quietly
         _rebuild_quietly()
         return
-    mtime = idx.stat().st_mtime
+    mtime = os.stat(idx).st_mtime
     if time.time() - mtime < _REBUILD_MIN_INTERVAL:
         return
     # The newest row's timestamp arrives from the same connection that did the
@@ -410,6 +415,7 @@ def _rebuild_when_stale(newest_ts: int | None = None) -> None:
             return
         newest = row[0] if row and row[0] else 0
     if newest and newest > mtime:
+        from tai.maintenance import _rebuild_quietly
         _rebuild_quietly()
 
 

package/tai/engcache.py

@@ -28,7 +28,11 @@ from __future__ import annotations
 
 import marshal
 import os
-from pathlib import Path
+
+# `pathlib` is deliberately not imported at module level: the one-shot suggest
+# loads this module on its warm path, and a warm cache reads no `Path` — only
+# `_cache_path`'s Path-in-Path-out contract for tests and tools that pass one
+# needs the type, and that import happens on the first call that wants it.
 
 # Bump when the cached shape changes (new fields on CmdStats, new maps, a new
 # serialization). 2: CmdStats gained `nf`. 3: pickle gave way to marshal, and
@@ -41,26 +45,46 @@ VERSION = 4
 _MAGIC = "tai-engine-m"
 
 
-def _cache_path(db: Path) -> Path:
+def _cache_path(db) -> "Path | str":
     # Beside the database, named for it: a scratch TAI_DB in a test cannot
     # stamp a cache over the developer's real one, and `tai uninstall` (which
     # removes the whole data directory) removes the cache with everything else.
+    # A `Path` in, a `Path` out; a string in, a string out — the one-shot path
+    # passes the string form so a warm process imports no pathlib at all.
     import hashlib
 
-    name = hashlib.sha1(str(db).encode("utf-8", "replace")).hexdigest()[:16]
-    return db.parent / f"engine-{name}.cache"
+    dsp = os.fspath(db)
+    name = hashlib.sha1(dsp.encode("utf-8", "replace")).hexdigest()[:16]
+    out = os.path.join(os.path.dirname(dsp), f"engine-{name}.cache")
+    if type(db) is str:
+        return out
+    from pathlib import Path
+    return Path(out)
+
+
+def _sibling(cp, name: str):
+    """`name` in the directory `cp` lives in, in `cp`'s own kind."""
+    out = os.path.join(os.path.dirname(os.fspath(cp)), name)
+    if type(cp) is str:
+        return out
+    from pathlib import Path
+    return Path(out)
 
 
-def get(db_path: Path, build) -> object:
+def get(db_path, build) -> object:
     """The built engine for `db_path`, loading a cached one when it is current.
 
-    `build` is called with no arguments and must return the engine; it runs at
-    most once per process, and only when the cache is missing or stale.
+    `db_path` may be a `Path` or a plain string — the one-shot path passes the
+    string form (`tai.paths.db_location`) so a warm process never imports
+    pathlib. `build` is called with no arguments and must return the engine;
+    it runs at most once per process, and only when the cache is missing or
+    stale.
     """
     if os.environ.get("TAI_NO_ENGINE_CACHE") == "1":
         return build()
+    dsp = os.fspath(db_path)
     try:
-        st = db_path.stat()
+        st = os.stat(dsp)
     except OSError:
         return build()          # no store yet: nothing to cache against
     key = (st.st_size, st.st_mtime_ns)
@@ -76,11 +100,12 @@ def get(db_path: Path, build) -> object:
         pass                    # torn, stale, or foreign: build instead
     eng = build()
     try:
-        tmp = cp.with_name(cp.name + f".tmp{os.getpid()}")
+        tmp = _sibling(cp, (cp.name if type(cp) is not str
+                            else os.path.basename(cp)) + f".tmp{os.getpid()}")
         with open(tmp, "wb") as f:
             f.write(f"{_MAGIC} {VERSION} {key[0]} {key[1]}\n".encode("ascii"))
             marshal.dump(_snapshot(eng), f, 4)
-        os.replace(tmp, cp)
+        os.replace(os.fspath(tmp), os.fspath(cp))
     except Exception:
         pass                    # a read-only or vanished directory is fine
     return eng

package/tai/engine.py

@@ -38,6 +38,14 @@ _LOG1P20 = math.log1p(20)
 # Half-life of a command's recency, in days, as `exp(-age / TAU)`.
 _TAU = 14.0
 
+# The store's longest-learned-command bound, imported from tai.store on first
+# use and kept here. `add` used to run `from tai.store import MAX_CMD_LEN`
+# on *every* call — a sys.modules lookup and attribute fetch each time, 20k
+# of them in one build_from_rows — because a module-level import would have
+# dragged sqlite3 and re into every process that loads the engine without
+# ever learning. The lazy global keeps the lazy import and pays it once.
+_MAX_CMD_LEN: int | None = None
+
 
 def hour_bucket(ts: int | None = None) -> int:
     try:
@@ -157,8 +165,11 @@ class Engine:
             return
         # The same bound is_recordable applies — imported here, where a row this
         # long is rare, rather than at module load, which every fast process pays.
-        from tai.store import MAX_CMD_LEN
-        if len(cmd) > MAX_CMD_LEN:
+        global _MAX_CMD_LEN
+        if _MAX_CMD_LEN is None:
+            from tai.store import MAX_CMD_LEN as _mcl
+            _MAX_CMD_LEN = _mcl
+        if len(cmd) > _MAX_CMD_LEN:
             return
         ts = ts if ts is not None else int(time.time())
         st = self.cmds.get(cmd)
@@ -266,10 +277,15 @@ class Engine:
                 on_path=None) -> dict:
         """Rank candidates for `prefix`.
 
-        `exclude` drops candidates before ranking. The engine itself never
-        touches the filesystem — it has to stay a sub-millisecond in-memory
-        ranker — so the caller decides policy (currently: commands whose paths
-        no longer exist) and passes the result in.
+        `exclude` drops candidates before ranking. It is read with `in` — a
+        set of names, or any per-name verdict holder such as the predictor's
+        `LazyStale`, which answers a candidate's path-liveness question the
+        first time it is consulted and remembers it — so a caller with an
+        expensive exclusion question pays it only for the names this query
+        actually walks. The engine itself never touches the filesystem — it
+        has to stay a sub-millisecond in-memory ranker — so the caller decides
+        policy (currently: commands whose paths no longer exist) and passes
+        the answer in.
 
         `on_path` is the caller's answer to one question — is this command's
         first word installed? — asked at most once per candidate, and only for

package/tai/fresh.py

@@ -34,9 +34,12 @@ below and by `TAI_FILE_ROOTS`, which adds roots to both.
 """
 from __future__ import annotations
 
-import glob
 import os
 
+# `glob` is deliberately not imported at module level: it drags fnmatch and re
+# (about 3ms) into every one-shot process, and only a query whose answer comes
+# from the disk ever globs. The functions below import it on first use.
+
 # How many files one root may contribute, and how many roots are read in all.
 # Both are shortlists, not truncation: the way to see more is to type more of
 # the word, which narrows every root at once. A downloads folder has a season of
@@ -159,7 +162,9 @@ def _scan(pattern: str, cut: int, written: str) -> list[tuple[float, str]]:
     built from mtimes, so the cap is applied after the sort.
     """
     try:
-        names = glob.glob(pattern)
+        from glob import glob as _glob
+
+        names = _glob(pattern)
     except (OSError, ValueError):
         return []
     out: list[tuple[float, str]] = []

package/tai/index.py

@@ -140,7 +140,13 @@ def bash_index_path() -> Path:
 
 
 def _zq(value: str) -> str:
-    return "'" + str(value).replace("'", "'\\''") + "'"
+    # The apostrophe is the rare case, and the scan for it is a C-speed `in`;
+    # quoting the common case was one str.replace call per index entry — 38k
+    # of them a rebuild — for a replace that never had anything to replace.
+    value = str(value)
+    if "'" not in value:
+        return f"'{value}'"
+    return "'" + value.replace("'", "'\\''") + "'"
 
 
 def _word_value(values: list[str]) -> str:

package/tai/maintenance.py

@@ -7,10 +7,14 @@ eventually reclaims it — a lock that outlives its process would stop every
 future rebuild, silently, forever.
 """
 import os
-import shutil
 import time
 from pathlib import Path
 
+# `shutil` is imported by the two functions that remove things, not at module
+# level: this module loads on the record path's freshness check, and shutil
+# dragged ~1.3ms of bz2/lzma/fnmatch with it for a question that usually ends
+# in one stat.
+
 
 def _lock_path() -> Path:
     from tai.store import db_path
@@ -63,6 +67,8 @@ def _owner_gone(lock: Path) -> bool:
             running = True       # no usable pid: assume a live holder
         if running:
             return False         # this boot, this minute, and still running
+    import shutil
+
     shutil.rmtree(lock, ignore_errors=True)
     return True
 
@@ -127,6 +133,8 @@ def _rebuild_index():
     the ones that do not go through _rebuild_quietly.
     """
     from tai.index import build
+    import shutil
+
     lock = _lock_path()
     if not _take_lock(lock):
         return None

package/tai/paths.py

@@ -30,7 +30,15 @@ from __future__ import annotations
 
 import os
 from functools import lru_cache
-from pathlib import Path
+
+# `pathlib` is deliberately NOT imported at module level. This module sits under
+# everything: the engine (which the keystroke-free one-shot path loads), the
+# store, and the spool, so a module-level import made every one of those
+# processes pay pathlib's own ~7ms — fnmatch, re and urllib.parse with it — for
+# a type only two builders of file names ever need. The functions here that
+# hand back a `Path` import it on first call instead; every other reader of
+# this module, and the warm engine-cache suggest path above all, imports
+# nothing heavier than `os`.
 
 # Verdicts. Only MISSING removes a candidate.
 EXISTS = "exists"
@@ -149,8 +157,28 @@ _UNANALYSABLE = set('$`*?[]{}<>|;&()!#\\\n\t"\'')
 
 # Cached (token, cwd) verdicts. Builds and purges ask about the same paths
 # thousands of times, and the filesystem does not change under one run.
+# Absolute and `~` tokens are cached under the empty cwd: they are true or
+# false in every directory, so one answer serves them all.
 _cache: dict[tuple[str, str], bool] = {}
 
+# Directories already judged with `os.path.isdir`, per process. `_resolve` used
+# to re-ask it for every token of every command against every recorded cwd —
+# a dozen stats per command on a build, and the same few directories every
+# time. The filesystem does not change under one run; that is the same promise
+# `_cache` above is kept under.
+_isdir: set[str] = set()
+_notdir: set[str] = set()
+
+
+def _is_dir(path: str) -> bool:
+    if path in _isdir:
+        return True
+    if path in _notdir:
+        return False
+    hit = os.path.isdir(path)
+    (_isdir if hit else _notdir).add(path)
+    return hit
+
 # Every account name on this machine, or None where they cannot be read. Read
 # once and only when a `~name` token actually turns up, because most machines
 # have no such command in their history at all and this is a question about the
@@ -184,10 +212,38 @@ def data_dir() -> Path:
     ~/.local/share would split the install across two directories and leave
     `tai uninstall` deleting one half of it and reporting complete.
     """
+    from pathlib import Path
+
     base = os.environ.get("XDG_DATA_HOME") or Path.home() / ".local" / "share"
     return Path(base) / "tai"
 
 
+def data_location() -> str:
+    """`data_dir()` as a plain string, with pathlib still unpaid.
+
+    The string form of the same decision, for the processes that join file
+    names onto it and never want a `Path`: `os.path.expanduser("~")` is the
+    same home `Path.home()` reads, and the join is the same join.
+    """
+    base = os.environ.get("XDG_DATA_HOME") or os.path.expanduser("~/.local/share")
+    return os.path.join(base, "tai")
+
+
+def db_location() -> str:
+    """`db_path()` as a plain string, with pathlib still unpaid.
+
+    The engine cache is keyed on the database file's own (size, mtime_ns), so
+    the one-shot suggest asks for this path before it can ask whether it needs
+    the store at all — and a warm cache reads neither sqlite3, re, nor
+    pathlib. Every caller that wants the type wraps this in `Path` via
+    `db_path()`; nothing else about the decision changes.
+    """
+    env = os.environ.get("TAI_DB")
+    if env:
+        return env
+    return os.path.join(data_location(), "history.db")
+
+
 def db_path() -> Path:
     """Where the history store lives — `TAI_DB`, or beside `data_dir()`.
 
@@ -201,7 +257,23 @@ def db_path() -> Path:
     re-export, because the writer and every reader of the store still say
     `store.db_path`.
     """
-    return Path(os.environ.get("TAI_DB") or data_dir() / "history.db")
+    from pathlib import Path
+
+    return Path(db_location())
+
+
+def index_location() -> str:
+    """The zsh index as a plain string — `TAI_INDEX`, or beside the data.
+
+    The string twin of `tai.index.index_path`, for the readers that only stat
+    the file: the record path's rebuild debounce asks "is the index older
+    than the newest row" once per recorded batch, and importing tai.index for
+    that stat pulled the engine, the knowledge loader and pathlib into every
+    flush. The env var is read identically, so the two names stay one
+    decision.
+    """
+    return os.environ.get("TAI_INDEX") or os.path.join(
+        data_location(), "zsh-index.zsh")
 
 
 def _unquote(token: str) -> str:
@@ -210,8 +282,18 @@ def _unquote(token: str) -> str:
     return token
 
 
+@lru_cache(maxsize=8192)
 def is_path_like(token: str) -> bool:
-    """True when `token` can only be read as a filesystem path."""
+    """True when `token` can only be read as a filesystem path.
+
+    Memoised: it is a pure function of the token, and the liveness walks ask it
+    for every token of every distinct command — the same few thousand strings
+    over and over, since a history repeats its paths. Measured on a 20k-row
+    history, the per-character scan was 58% of a warm `tai suggest`'s process
+    and a quarter of `tai refresh`; the cache turns both into one C-speed dict
+    hit per distinct token. Bounded, so a long-running dashboard cannot grow
+    it without limit.
+    """
     if not token or token.startswith("-") or "=" in token:
         return False
     if any(ch in _UNANALYSABLE for ch in token):
@@ -319,10 +401,14 @@ def _resolve(token: str, cwds) -> str:
             return UNKNOWN
         return EXISTS if os.path.exists(os.path.expanduser(token)) else MISSING
     if os.path.isabs(token):
-        return EXISTS if os.path.exists(token) else MISSING
+        key = (token, "")
+        hit = _cache.get(key)
+        if hit is None:
+            hit = _cache[key] = os.path.exists(token)
+        return EXISTS if hit else MISSING
     # A relative path is only knowable from a directory it was actually run in.
     # With no such directory the honest answer is "no opinion".
-    known = [c for c in cwds if c and os.path.isdir(c)]
+    known = [c for c in cwds if c and _is_dir(c)]
     if not known:
         return UNKNOWN
     for cwd in known:

package/tai/predictor.py

@@ -14,10 +14,11 @@ import time
 
 from tai.engine import WRAPPERS, Engine
 from tai.fresh import files
-from tai.paths import alive_in, db_path, takes_file
+from tai.paths import (MISSING, alive_in, command_verdict, db_location,
+                       enabled, takes_file)
 
 _E: Engine | None = None
-_STALE: frozenset = frozenset()
+_STALE: "LazyStale | frozenset" = frozenset()
 
 # Is this command's first word installed? Asked once per word per process and
 # kept here, because PATH does not change under a running process in any way
@@ -29,25 +30,126 @@ _STALE: frozenset = frozenset()
 _WHICH: dict[str, bool] = {}
 
 
+def _path_lookup(word: str) -> bool:
+    """`shutil.which(word) is not None`, answered without importing shutil.
+
+    shutil was 5ms of a warm one-shot suggest — and it dragged re, fnmatch,
+    bz2 and lzma in behind it — for a PATH scan this module can do with os
+    alone. The walk is shutil.which's own, POSIX branch, line for line: a
+    word with a directory part is looked up directly; an empty PATH element
+    means the current directory; a hit must exist, be executable, and not be
+    a directory. Only the Windows PATHEXT machinery is absent — the plugin
+    and the installer are Linux-only anyway.
+    """
+    dirname, name = os.path.split(word)
+    if dirname:
+        dirs = [dirname]
+    else:
+        path = os.environ.get("PATH")
+        if path is None:
+            try:
+                path = os.confstr("CS_PATH")
+            except (AttributeError, ValueError):
+                path = os.defpath
+        if not path:
+            return False
+        dirs = os.fsdecode(path).split(os.pathsep)
+    seen: set[str] = set()
+    for d in dirs:
+        norm = os.path.normcase(d)
+        if norm in seen:
+            continue
+        seen.add(norm)
+        cand = os.path.join(d, name)
+        if (os.path.exists(cand) and os.access(cand, os.F_OK | os.X_OK)
+                and not os.path.isdir(cand)):
+            return True
+    return False
+
+
 def _on_path(word: str) -> bool:
     """Whether `word` resolves to an executable on this machine's PATH."""
-    import shutil
     hit = _WHICH.get(word)
     if hit is None:
-        hit = _WHICH[word] = shutil.which(word) is not None
+        hit = _WHICH[word] = _path_lookup(word)
     return hit
 
 
-def _stale_for(eng: Engine) -> set:
-    """Commands whose paths no longer exist, per the engine's own cwd records.
+class LazyStale:
+    """The engine's stale set, asked lazily and remembered per command.
+
+    `paths.stale_in` walks every distinct command's every token up front, and
+    the one-shot suggest paid that whole walk — measured at more than half of
+    its process on a 20k-row history — before ranking a handful of candidates
+    for one prefix. The verdict for one command is a pure function of the
+    command, the directories it was recorded in, and the directory the answer
+    is shown in, so it can be asked per candidate instead: the engine consults
+    `exclude` for exactly the names it would have filtered, and only those
+    verdicts are ever computed. For `tai suggest git ` that is the ~300
+    candidates behind the prefix instead of every command in the store; for an
+    empty prefix it is the same walk, deferred.
+
+    The full walk is still available — `materialize`, for the one reader that
+    counts the set, the dashboard's state panel. Behaves like a set for every
+    question the engine and the web page ask: `in`, `len`, truthiness.
+
+    The evidence rule is `stale_commands`' own, verbatim: a command is stale
+    when any of its path-like tokens is MISSING, judged from the directories
+    it was recorded in plus the one fallback directory (the cwd the answer is
+    shown in, appended only when the records do not already have it), and
+    `TAI_SKIP_PATH_CHECK=1` turns the whole question off.
+    """
+
+    __slots__ = ("_eng", "_cwd", "_memo")
+
+    def __init__(self, eng: Engine, cwd: str = ""):
+        self._eng = eng
+        self._cwd = cwd or ""
+        self._memo: dict[str, bool] = {}
+
+    def _ask(self, cmd: str) -> bool:
+        hit = self._memo.get(cmd)
+        if hit is None:
+            if not enabled():
+                return False
+            st = self._eng.cmds.get(cmd)
+            cwds = list(st.cwd) if st is not None else []
+            if self._cwd and self._cwd not in cwds:
+                cwds.append(self._cwd)
+            hit = self._memo[cmd] = command_verdict(cmd, cwds) == MISSING
+        return hit
+
+    def __call__(self, cmd: str) -> bool:
+        return self._ask(cmd)
+
+    def __contains__(self, cmd: str) -> bool:
+        return self._ask(cmd)
+
+    def __bool__(self) -> bool:
+        # Truthy so the engine always consults the verdicts; an all-alive
+        # history filters to exactly what it filtered when the walk was eager.
+        return True
+
+    def __len__(self) -> int:
+        self.materialize()
+        return sum(1 for v in self._memo.values() if v)
+
+    def materialize(self) -> "LazyStale":
+        """Ask every command in the engine once, so `len` is the full count."""
+        for cmd in self._eng.cmds:
+            self._ask(cmd)
+        return self
+
+
+def _stale_for(eng: Engine) -> LazyStale:
+    """The stale question for this engine, asked lazily.
 
     The one-shot suggestion is shown in the directory the suggest process runs
     in, so the fallback cwd is passed explicitly here — and only here. The
     index builder uses recorded evidence alone, because its snapshot is shown
     in every directory, not just this one.
     """
-    from tai.paths import stale_in
-    return stale_in(eng, os.getcwd())
+    return LazyStale(eng, os.getcwd())
 
 
 def _build_engine() -> Engine:
@@ -87,10 +189,12 @@ def suggest(prefix: str = "", cwd: str = "", repo: str = "",
     if _E is None:
         # A fresh process rebuilds the engine from SQLite unless a disk cache
         # taken by an earlier process is still current — see tai/engcache.py.
-        # The path-liveness set is deliberately NOT cached: it answers against
-        # the directory this process runs in, which changes call to call.
+        # The path-liveness set is deliberately NOT cached across processes: it
+        # answers against the directory this process runs in, which changes
+        # call to call. The store is named as a plain string so a warm cache
+        # imports no pathlib, no sqlite3 and no re — see tai.paths.db_location.
         from tai.engcache import get
-        _E = get(db_path(), _build_engine)
+        _E = get(db_location(), _build_engine)
         _STALE = _stale_for(_E)
     res = _E.suggest(prefix=prefix or "", cwd=cwd, repo=repo, branch=branch,
                      last_commands=last_commands or [], limit=limit, temp=temp,
@@ -138,7 +242,7 @@ def explain(prefix: str, cmd: str, cwd: str = "", repo: str = "",
     global _E, _STALE
     if _E is None:
         from tai.engcache import get
-        _E = get(db_path(), _build_engine)
+        _E = get(db_location(), _build_engine)
         _STALE = _stale_for(_E)
     out = _E.explain(prefix or "", cmd, cwd=cwd, repo=repo, branch=branch,
                      last_commands=last_commands or [], on_path=_on_path)

package/tai/spool.py

@@ -33,6 +33,8 @@ from __future__ import annotations
 import os
 import time
 
+from tai.paths import data_location
+
 RS = "\x1e"
 US = "\x1f"
 
@@ -59,7 +61,9 @@ def spool_path() -> str:
     The answer is a plain path string, not a `Path`: this module loads on the
     record fallback and the flush, and importing pathlib costs about 9ms of
     enum, re and urllib.parse — per process, for what is here only string
-    plumbing. The one caller that genuinely wants a `Path` wraps it itself.
+    plumbing. The default is joined with os.path from the same base
+    `tai.paths.data_location` reads, so the module imports nothing heavier
+    than `os`; the one caller that genuinely wants a `Path` wraps it itself.
     """
     env = os.environ.get("TAI_SPOOL")
     if env:
@@ -69,8 +73,7 @@ def spool_path() -> str:
         if "/" in db:
             return db.rsplit("/", 1)[0] + "/spool.log"
         return "spool.log"
-    from tai.paths import data_dir
-    return os.path.join(str(data_dir()), "spool.log")
+    return os.path.join(data_location(), "spool.log")
 
 
 def spool_append(cmd: str, cwd: str = "", exit_code: int = 0,

package/tai/store.py

@@ -6,10 +6,15 @@ import re
 import sqlite3
 import time
 from contextlib import contextmanager
-from pathlib import Path
 
 from tai.paths import enabled as paths_enabled
 
+# `pathlib` is not imported at module level on purpose: this module loads on
+# the record and flush paths — once per batch the shells spool — and the type
+# is needed only by the history-import walk (`_history_files`). A module-level
+# import made every record pay pathlib's ~4ms and its urllib.parse/ipaddress
+# chain for a code path that runs on `tai refresh`, not on recording.
+
 # The longest command worth learning. A paste — a curl with its headers and
 # cookies, a heredoc — is not vocabulary: it is never retyped from memory, and
 # painted back as a hint it wraps the screen out of existence (the report that
@@ -20,7 +25,21 @@ from tai.paths import enabled as paths_enabled
 MAX_CMD_LEN = 1000
 
 # A command must be safe to persist and useful to suggest before it is kept.
-_SECRET = re.compile(r"(password|secret|token|AKIA|-----BEGIN)", re.I)
+# One reject scan, not two: is_recordable runs on every row the engine builds
+# from and every frame the spool drains, and two `.search` calls per row were
+# 20k regex dispatches a build for what one alternation answers. The two rules
+# it joins, in order:
+#
+#   * a secret-shaped word — `password`, `secret`, `token`, an AWS key id,
+#     a PEM header — matched case-insensitively, scoped inside `(?i: …)` so
+#     the rest of the pattern keeps its own exact letter-cases;
+#   * a session-persistence harness envelope, matched case-sensitively.
+_REJECT = re.compile(
+    r"(?i:password|secret|token|AKIA|-----BEGIN)"
+    r"|__[A-Za-z0-9]+_(?:START|END)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-"
+    r"[0-9a-f]{4}-[0-9a-f]{12}__"
+    r"|__[a-z0-9_]*status=\$\?"
+)
 
 # The raw-control-byte half of the filter, at C speed: this runs once per row
 # the engine builds from, and the previous per-character `any(ord(ch) < 32 …)`
@@ -73,7 +92,7 @@ def is_recordable(cmd: str) -> bool:
     # sequence's continuation bytes are all 0x80 and up.)
     if _CTRL.search(cmd):
         return False
-    return not (_SECRET.search(cmd) or _WRAPPER.search(cmd))
+    return not _REJECT.search(cmd)
 
 
 def db_path() -> Path:
@@ -371,6 +390,8 @@ def count() -> tuple[int, int]:
 
 def _history_files(home: Path) -> list[Path]:
     """Return supported history files, including a custom HISTFILE."""
+    from pathlib import Path
+
     candidates: list[Path] = []
     custom = os.environ.get("HISTFILE", "").strip()
     if custom:
@@ -418,6 +439,8 @@ def _import_rows(con: sqlite3.Connection) -> int:
     """
     imported = 0
     now = int(time.time())
+    from pathlib import Path
+
     home = Path.home()
     for f in _history_files(home):
         try:

package/tai/typo.py

@@ -254,12 +254,26 @@ def shadow_map(eng, lines=None) -> dict[str, str]:
     for c, bag in counts.items():
         for ch in low[c]:
             bag[ch] = bag.get(ch, 0) + 1
+    # The evidence each line carries, read once: the tuple a target must beat.
+    ev_of = {c: (eng.cmds[c].success, eng.cmds[c].freq, eng.cmds[c].last_ts)
+             for c in names}
     groups: dict[str, dict[int, list[str]]] = {}
     for c in names:
         groups.setdefault(low[c].split(" ", 1)[0], {}).setdefault(len(c), []).append(c)
     # The full-tie spelling to stand: all-lowercase first (commands are
     # lowercase; the capitalised twin is the accident), byte order otherwise.
     tkey = {c: (0, c) if low[c] == c else (1, c) for c in names}
+    # Every bucket is walked strongest-first, ties by the likelier spelling:
+    # the search can then stop at the first candidate that survives the gates,
+    # because no later one can beat it — the same evidence order the map's
+    # target rule asks for, laid out along the scan. The walk used to test the
+    # letter gates on the whole bucket and keep the best survivor; now the
+    # gates run only on the head of the bucket, the few candidates strong
+    # enough to be a target at all, which is where the map's time went.
+    for bucket_lists in groups.values():
+        for ln, members in bucket_lists.items():
+            members.sort(key=lambda c: (-ev_of[c][0], -ev_of[c][1],
+                                        -ev_of[c][2], tkey[c]))
     out: dict[str, str] = {}
     for cmd in names:
         st = eng.cmds[cmd]
@@ -270,12 +284,24 @@ def shadow_map(eng, lines=None) -> dict[str, str]:
             continue
         s_set = sets[cmd]
         s_bag = counts[cmd]
-        ev = (st.success, st.freq, st.last_ts)
-        best: tuple[tuple[int, int, int], str] | None = None
-        for ln in range(len(cmd) - 2, len(cmd) + 3):
+        ev = ev_of[cmd]
+        len_cmd = len(cmd)
+        best: str | None = None
+        best_oev: tuple[int, int, int] | None = None
+        for ln in range(len_cmd - 2, len_cmd + 3):
             for other in buckets.get(ln, ()):
                 if other == cmd:
                     continue
+                oev = ev_of[other]
+                # The target must be the stronger spelling — or, on a full
+                # tie, the likelier spelling (the tie bullet above). Anything
+                # weaker is somebody else's shadow, not this line's habit.
+                # The bucket is ordered strongest-first, so the first candidate
+                # that fails here fails for every candidate after it too: one
+                # comparison ends the bucket, where the walk used to gate-test
+                # hundreds of lines that could never have been the target.
+                if oev < ev or (oev == ev and tkey[other] > tkey[cmd]):
+                    break
                 o_set = sets[other]
                 if len(o_set - s_set) > 2 or len(s_set - o_set) > 2:
                     continue
@@ -290,20 +316,20 @@ def shadow_map(eng, lines=None) -> dict[str, str]:
                         surplus += extra
                         if surplus > 2:
                             break
-                if surplus > 2 or surplus - (len(cmd) - len(other)) > 2:
-                    continue
-                ost = eng.cmds[other]
-                oev = (ost.success, ost.freq, ost.last_ts)
-                # The target must be the stronger spelling — or, on a full
-                # tie, the likelier spelling (the tie bullet above). Anything
-                # weaker is somebody else's shadow, not this line's habit.
-                if oev < ev or (oev == ev and tkey[other] > tkey[cmd]):
+                if surplus > 2 or surplus - (len_cmd - len(other)) > 2:
                     continue
                 if lev1(low[cmd], low[other], 2) > 2:
                     continue
-                if best is None or oev > best[0] or \
-                        (oev == best[0] and tkey[other] < tkey[best[1]]):
-                    best = (oev, other)
+                # Strongest-first order says this survivor is the best target
+                # its own bucket holds: an equal-evidence one behind it spells
+                # itself less plausibly, and a weaker one is no target at all.
+                # The five length buckets are still compared against each
+                # other — a stronger target may sit two lengths away — so the
+                # survivor is kept and the next bucket is asked.
+                if best is None or oev > best_oev or \
+                        (oev == best_oev and tkey[other] < tkey[best]):
+                    best, best_oev = other, oev
+                break
         if best is not None:
-            out[cmd] = best[1]
+            out[cmd] = best
     return out