tensor-grep-find-and-route

name	tensor-grep-find-and-route
description	Use when vocabulary-mismatched queries need whole-repo hybrid search via tg find (BM25 + optional dense RRF, no regex pre-filter), or when verifying context-render vs edit-plan target agreement with tg route-test before trusting an edit plan. Distinct from tg search --rank/--semantic (those re-rank an existing regex match set).

tensor-grep find + route-test

Verified against tg 1.110.14 (2026-08-11; prior full dogfood 2026-07-21 WSL workspace sweep at v1.91.0).

When to use

Need	Command
Natural-language / mismatched vocabulary over a whole repo (no pattern pre-filter)	tg find "query" PATH --json
Confirm context-render and edit-plan agree on primary file/symbol/line	tg route-test PATH "query" --json

Do not use tg find as a grep replacement (--format rg is intentionally absent). Prefer scoped PATH (REPO/src) first.

tg find

tg find "session daemon timeout handling" REPO/src --deadline 20 --json
tg find "session daemon timeout handling" REPO --deadline 30 --json

• Multi-word NL examples like the above are dense-favored by default (flip SHIPPED #191/#634, first released v1.79.0; re-verified 2026-08-12 against v1.110.14): with TG_FIND_DENSE_WEIGHT unset (or malformed/non-finite), a genuinely multi-word query gets the adaptive 5.0 weight; single-token queries stay pinned at 1.0. TG_FIND_DENSE_WEIGHT=1.0 is the explicit BM25-only (equal-weight) opt-out. See tensor-grep-semantic-search-campaign STATUS UPDATE 4.
• Bounded by default (--max-repo-files, --deadline, internal chunk cap).
• Truncation → result_incomplete + exit 2 (never silent partial-as-complete).
• Bare tg find "query" with no PATH does NOT hit the search fast-refuse — find defaults PATH to . (it is not bootstrap-intercepted; the IMPLICIT_SEARCH_WALK_FILE_CEILING=1500 fast-refuse is a tg search front-door behavior, v1.92.3). find bounds itself via --max-repo-files (default 2000) plus --deadline/chunk caps, and marks truncation honestly (result_incomplete + exit 2). Still: always scope tg find to a PATH — for ranking quality and so a big root doesn't truncate the corpus.
• Scale evidence: tg find's repo walk shares the exact same _iter_repo_files walker as orient/inventory/search (_execute_find calls it directly). A 300k+-file multi-project workspace dogfood found deadline-bounded surfaces on that walker hold up well in general; the one known low-priority edge — a non-lazy os.scandir read of a single pathological, huge directory inside _iter_repo_files that can outrun --deadline before the per-file check fires — was observed via inventory --deadline but applies equally to find --deadline (same walk call, same missing mid-scandir check). Rare; another reason to scope tg find to a PATH rather than lean on --deadline alone at repo root.
• Dense leg: prefer tg install-dense (one-shot pip + pinned potion-code-16M). Without it, find is BM25-only and reports rank_fallback_reason — supported, not silent. The fallback message is now the literal retrieval_dense.py string (A12(a), v1.93.0/#705): semantic ranking unavailable: model2vec not installed -- run `tg install-dense` (or pip install 'tensor-grep[semantic]') — every dense-absent hint across the CLI leads with tg install-dense the same way, not just this one.
• Which leg ran is reported IN the payload (src/tensor_grep/cli/main.py:1663-1664): routing_backend is HybridFindBackend when the dense index loaded, else Bm25FindBackend; routing_reason is find_bm25_dense_rrf or find_bm25_only. Both are REQUIRED by tests/schemas/tg_output.schema.json (typed minLength: 1), so a null there is a contract violation, not a shrug — they were null on every tg find --json payload until v1.111.6. rank_fallback_reason and routing_reason are DIFFERENT signals and must not be conflated: routing_reason says WHAT RAN, rank_fallback_reason says WHY the dense leg is absent. A consumer that reads only one of them cannot distinguish "hybrid ran" from "BM25 ran because model2vec is missing".
• Dogfood (1.91.0): find_src ~8.4s PASS (BM25 before install-dense); find_src_postdense ~21s PASS (no fallback). Not re-collected since v1.91.0 — before citing these as current, re-run on the shipped wheel as an isolated cold-process pass per case: a warm end-to-end dogfood run can hide a since-changed function's real cost in either direction, and find_src_postdense bundles the one-time potion-code-16M model load, so its warm/cold status matters.

tg route-test

tg route-test REPO/src "improve session daemon timeout" --json

• Emits agreement + per-field agreement_details (file/symbol/line).
• Dogfood (1.91.0): agreement=true on tensor-grep/src (~27s alone; the old "can exceed 60s under WSL suite load — budget 90s" guidance is SUPERSEDED by the default 60s deadline — see the next bullet). This evidence predates the #693/#250 primary-target ranking fix (v1.91.2) that it is meant to validate — re-collect the agreement=true proof on a current version before citing it as current confirmation of post-fix routing agreement.
• SUPERSEDED (2026-08-12 retention pass, verified against v1.110.14 / base 568065a): since #672 (first released v1.81.21 — NOT v1.100.0), route-test defaults to a 60s wall-clock --deadline, reusing DEFAULT_AGENT_CLI_DEADLINE_SECONDS = 60.0 (defined in agent_capsule_constants.py, re-exported by agent_capsule.py; find it with grep -rn "DEFAULT_AGENT_CLI_DEADLINE_SECONDS = " src/tensor_grep/cli/ — deliberately NO line number, because this citation previously pinned agent_capsule.py:34, which is an unrelated import after the constants split; wired at grep -n "agreement_basis" src/tensor_grep/cli/main.py — deadline defaulting :11037-11081, partial stamping :10982-10993). Under defaults it therefore CANNOT exceed ~60s: when either route's build is truncated, the payload additively stamps partial=true, partial_reason="deadline", deadline_limit (which side(s) truncated), and agreement_basis="partial" — the tell an agent MUST check before trusting agreement at face value; an agreement computed from one or two truncated sides exits 2 and must not read as a full-confidence verdict. A complete run omits all four fields (byte-identical to the pre-#672 payload). --deadline N overrides the default; --no-deadline restores unbounded running (only then can it exceed 60s).
• Use before trusting an edit-plan primary when routes might diverge.
• For the routine single-target case, tg prepare already returns a primary_target + confidence in one call and explicitly supersedes the multi-step orient→search→→→→→ loop (see ) — reach for directly when you need the explicit per-field breakdown, or when reconciling separately-made / calls.

Related

• tensor-grep, tensor-grep-enterprise-agent, tensor-grep-semantic-search-campaign (build history for dense/RRF)
• tensor-grep-prepare — one-call edit readiness that already covers the routine route-test-equivalent check; prefer it for ordinary edits, reach for tg route-test directly for the explicit per-field breakdown
• tg search --rank / --semantic re-rank regex hits — different contract than tg find