terminal-ai-helper 2.3.2 → 2.3.4

package/VERSION

@@ -1 +1 @@
-2.3.2
+2.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "terminal-ai-helper",
-  "version": "2.3.2",
+  "version": "2.3.4",
   "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/zsh/widgets.zsh

@@ -29,6 +29,29 @@ typeset -g _TAI_PASTE_PREV=""
 typeset -gi _TAI_PASTE_QUIET=0
 typeset -gi _TAI_PASTE_JUMP=25
 
+# The clock the chunk rule reads, the redraw that raised the quiet, and the
+# query an arrival skipped. zsh/datetime is what makes $EPOCHREALTIME exist;
+# on a zsh too old for it the chunk rule is inert and the two bounds above
+# keep the behaviour this file was shipped with — the module load is best-
+# effort on purpose.
+zmodload zsh/datetime 2>/dev/null
+# A fiftieth of a second, in microseconds. The fastest coalesced burst of
+# ordinary typing is a read every few tens of milliseconds (a hand, not a
+# terminal, is the thing being told apart), and the harness's own quiet
+# window is built on the same arithmetic.
+typeset -gi _TAI_PASTE_CHUNK_US=20000
+# How many edit events at terminal speed make a paste. Five insertions in a
+# row, each within a fiftieth of a second of the last, is 250 characters a
+# second — no hand does that; keyboard auto-repeat at its fastest stock rate
+# (about 30 a second) does not either, and a rate set past 50 a second only
+# holds the quiet while the key is held, which costs one stale hint.
+typeset -gi _TAI_PASTE_MIN_RUN=5
+typeset -g _TAI_PASTE_TICK=""
+typeset -gi _TAI_PASTE_RUN=0
+typeset -gi _TAI_PASTE_NEW=0
+typeset -gi _TAI_PASTE_FAST=0
+typeset -gi _TAI_Q_OWED=0
+
 # Is the line *typed*? A history line is not: Up fills the buffer with a
 # command the user ran once, and on that buffer Down means "the next history
 # entry" — it did not mean "open the list" until something was typed. The flag
@@ -39,18 +62,71 @@ typeset -gi _TAI_PASTE_JUMP=25
 # a line nobody typed, with the line itself as its only row.
 typeset -gi _TAI_TYPED=0
 
+# $EPOCHREALTIME as whole microseconds in REPLY, and false where there is no
+# clock. String surgery, not arithmetic on the float: the fraction is padded
+# and cut to six digits by hand, and `10#` keeps a fraction that opens in a
+# zero from being read as octal. This build's fraction runs longer than six
+# digits, which is why the cut is there at all.
+_tai_now_us() {
+  REPLY=0
+  [[ -n "$EPOCHREALTIME" ]] || return 1
+  local fr="${EPOCHREALTIME#*.}"
+  REPLY=$(( ${EPOCHREALTIME%%.*} * 1000000 + 10#${(r:6::0:)fr} ))
+}
+
 _tai_paste_state() {
   # The unwrapped case: how far the buffer moved since the last redraw. One
   # character in either direction is a keystroke — typed or removed — and ends
   # the quiet; more than _TAI_PASTE_JUMP at once is an arrival and starts it.
-  # Everything between leaves the flag as it is.
+  # Everything between leaves the flag as it is — unless the clock says it is
+  # a chunk of a paste, which is the branch below.
+  _TAI_PASTE_NEW=0
   local -i d=$(( ${#BUFFER} - ${#_TAI_PASTE_PREV} ))
   (( d < 0 )) && d=$(( -d ))
+  local -i now_us=0
+  _tai_now_us && now_us=$REPLY
+  # Terminal speed, judged against the previous redraw: an insertion within a
+  # fiftieth of a second of the last one is not a hand. The hook fires per
+  # widget, so a three-character chunk is three calls — two of them one
+  # character apart, microseconds together — and the last character of every
+  # chunk looks exactly like a keystroke. Without the clock, the tail of a
+  # paste would end the quiet that the middle of the same paste raised.
+  local -i fast=0
+  (( now_us && ${#_TAI_PASTE_TICK} )) && \
+    (( now_us - _TAI_PASTE_TICK < _TAI_PASTE_CHUNK_US )) && fast=1
+  _TAI_PASTE_FAST=$fast
+  # The run: consecutive edit events at terminal speed. The hook fires per
+  # widget, so a pasted character and a typed character both arrive as d==1 —
+  # the buffer cannot tell them apart, and neither bound above sees anything
+  # but one keystroke at a time. Only the clock separates a hand from a
+  # terminal, and only a run of them separates a paste from one lucky
+  # keystroke: two fast keys in a row happens to hands (rollover), twenty in
+  # a row does not.
+  if (( d != 0 )) && (( fast )); then
+    _TAI_PASTE_RUN+=1
+  else
+    _TAI_PASTE_RUN=0
+  fi
   if (( d == 1 )); then
-    _TAI_PASTE_QUIET=0
+    (( fast )) || _TAI_PASTE_QUIET=0
   elif (( d > _TAI_PASTE_JUMP )); then
+    (( _TAI_PASTE_QUIET )) || { _TAI_PASTE_QUIET=1; _TAI_PASTE_NEW=1; }
+  elif (( d > 1 )); then
+    # A coalesced insertion — several characters in one read — is one event
+    # that moved more than a keystroke and less than an arrival. At human
+    # speed it is a typing burst like any other; at terminal speed it is a
+    # chunk of a paste, and the run below will agree with it.
+    (( fast && ! _TAI_PASTE_QUIET )) && { _TAI_PASTE_QUIET=1; _TAI_PASTE_NEW=1; }
+  fi
+  # Enough of a run is a paste, whoever delivered it. Raised once — the
+  # crossing is the arrival, and everything after it rides the same quiet —
+  # and ended by the next edit at human speed, which is the keystroke rule
+  # above doing what it always did.
+  if (( _TAI_PASTE_RUN >= _TAI_PASTE_MIN_RUN && ! _TAI_PASTE_QUIET )); then
     _TAI_PASTE_QUIET=1
+    _TAI_PASTE_NEW=1
   fi
+  (( now_us )) && _TAI_PASTE_TICK=$now_us
   _TAI_PASTE_PREV="$BUFFER"
 }
 
@@ -158,7 +234,27 @@ _tai_update() {
     (( ours_was )) && POSTDISPLAY=""
   fi
   _tai_paste_state
-  _tai_query "$BUFFER" "$_TAI_LAST"
+  # A paste is not a query — all of it, not only its menu. The redraw that
+  # raised the quiet answers nothing: the line is still arriving, and a full
+  # query on a real index for a line nobody has read is the cost the chunk
+  # rule exists to stop. What it skips it owes — one query, at the first
+  # redraw that is not itself arriving at terminal speed, the keystroke that
+  # ends the paste or any edit after it — by which time the buffer is the
+  # line the user is reading, so the answer is the one they would have asked
+  # for. The hook fires per widget, so the middle of a paste owes and the
+  # tail of it is still fast: paying at any fast redraw would put the storm
+  # back one chunk at a time. The envelope keeps its single query: quiet
+  # raised by the paste widget is not an arrival this hook raised, and one
+  # query for a line that arrived at once is the deal the bracketed-paste
+  # tests have always held.
+  if (( _TAI_PASTE_NEW )); then
+    _TAI_Q_OWED=1
+  elif (( _TAI_Q_OWED )) && (( ! _TAI_PASTE_FAST )); then
+    _TAI_Q_OWED=0
+    _tai_query "$BUFFER" "$_TAI_LAST"
+  elif (( ! _TAI_Q_OWED )); then
+    _tai_query "$BUFFER" "$_TAI_LAST"
+  fi
   # The extends test folds case — the lookup that filled _TAI_BEST does, and
   # `ls down` reaching `ls Downloads` is the point of it — and the strip is
   # positional: the head of the best line that matched is the buffer's own
@@ -589,9 +685,14 @@ _tai_line_init() {
   _TAI_DREW=0
   _TAI_MENU_DISMISS=""
   # A new line is a new story: no paste has arrived on it yet, and nothing
-  # on it is typed.
+  # on it is typed. An owed query belongs to the line that skipped it — a
+  # debt carried past the prompt would be paid against a line nobody pasted.
   _TAI_PASTE_PREV=""
   _TAI_PASTE_QUIET=0
+  _TAI_PASTE_TICK=""
+  _TAI_PASTE_NEW=0
+  _TAI_PASTE_FAST=0
+  _TAI_Q_OWED=0
   _TAI_TYPED=0
   # And no directory snapshot is worth keeping either: the file answer reads
   # its snapshots for a second after taking them, and a line that starts now

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