Tensor Grep Large Repo Scale Campaign

tensor-grep — Large-Repo Scale-Honesty Campaign

A decision-gated runbook for the project's hardest live problem: making tg bounded and honest at customer scale. Two failure shapes, one contract:

1. Never hang. Every scan path has a wall-clock bound; when the bound trips it returns a partial result, never spins forever.
2. Never silently lie. A truncated/partial result is flagged (result_incomplete / partial in JSON, an exit-2 signal for symbol commands, a stderr warning) so an agent can tell "complete zero" from "gave up early." A quietly-empty result that reads as "no matches / no callers / dead code" is the one bug a context tool cannot ship.

This skill is the campaign map: what already shipped, what is still open, the exact commands + expected numbers at each gate, the wrong paths that are fenced off, and how promotion routes through change-control. You ship nothing user-visible from this skill without beating a measurable gate and a conscious flag-flip (Phase 4).

Why this is the live frontier (receipts)

• --deadline is now a hard end-to-end wall-clock bound on the graph commands (task #52, CLOSED by PR #478 / 67f9779, shipped v1.54.3). Receipt (2026-07-05, on a real 1884-file TypeScript repo, pre-#396): tg callers QueryEngine --deadline 10 took **25 s** (not ~10 s), and a direct deadline_seconds=8 call took >90 s. Root cause: build_symbol_callers_from_map (the caller-scan) re-reads/re-parses candidate files in an any()-loop per definition, so "each stage is bounded" did not make the pipeline bounded. #478 closed the residual gap a verify-plan-against-code pass found after #396/#440: four loops still had no wall-clock bound -- (A) _iter_repo_files' file-tree walk (count-only bound, no deadline), (B) _relevant_tests_for_symbol's two unguarded any() loops (the dominant cause on a high-fan-out symbol like "main", confirmed a 3x-recurring P0), (C) build_symbol_impact_from_map had no deadline parameter at all, and (D) the string_refs second pass in build_symbol_refs_from_map. All four now fold into the existing _DeadlineBreakFlag/partial/deadline_limit machinery, guarded if deadline_monotonic is not None so an undeadlined caller sees byte-identical behavior. See S2 for what this does and does not close (the #390 daemon-path gap is explicitly separate).
• #396 (v1.39.1) shipped a caller-scan re-parse cache + Path.resolve() memoization — the code comment measures ~18 s of ~22 s wall time was redundant resolve() churn (src/tensor_grep/cli/repo_map.py:76-80), claims 7.9x on central symbols. So the pre-#396 receipt numbers are STALE — Phase 0 re-measures at HEAD.
• The unscoped-tg search hang was real and is now fixed, not in-flight. AGENTS.md (grep -n "hangs ~600 s then errors" AGENTS.md; was :378, now :480 — drifted +102 lines this pass, same-size drift as the other AGENTS.md cites below, consistent with one insertion earlier in that file) still narrates the pre-fix symptom ("hangs ~600 s then errors" because tg's own index dirs + a vendored tree were not auto-excluded) — that doc lags. The fix, #400, shipped in v1.40.4 (bb14abe) and was hardened further by #413 (v1.42.0) and #428; see §1 below. Do not present this as an open bug or an unmerged PR.
• Whole-repo GRAPH commands (agent / callers / blast-radius / orient) are SLOW AT SCALE, not hung — scope to a package root. On a big tree the graph is O(files): tg agent . / tg orient . walk + parse the whole repo. Native Windows they COMPLETE (agent ~18s on an 872-file repo, workspace orient . ~48s on 50k files) but they are not fast. The agent-honest usage on large trees is a package root — tg agent REPO/src "task", tg callers REPO/src SYMBOL — 3-5x faster. Two CPU latency wins shipped 2026-07-11 (v1.63.3 deweight #534 removed a per-file resolve() hot loop from the shared hot path; v1.63.4 parse-cache #535 deduped the 2-3x Python parse, 36% faster on a warm re-query); the remaining scan cost is inherent and is the warm-daemon's job (#94).
• A "whole-repo hang past 60-90s" reported from WSL over /mnt/c is a 9p-filesystem ARTIFACT, NOT a tg deadlock. WSL reading a Windows-mounted tree is ~3-5x slower than native NTFS at the file-walk + stat()/realpath() these commands do, which tips scope-proportional work past a test timeout. Reproduce a WSL latency report NATIVELY (Windows or native Linux, not /mnt/c) before treating it as a tg bug — the 2026-07-11 v1.63.2 "10-timeout P0 regression" dogfood was exactly this (native: every flagged command completed). Memory: tensor-grep-wsl-mnt-c-latency-artifact-2026-07-11.
• Real-world scale dogfood (2026-07-23, c:/dev workspace, 300k+ files across dozens of nested projects — not a synthetic reference repo) confirms the shipped mechanisms hold at genuinely large scale, not just on the TypeScript reference repo. tg orient bounds itself via scan_limit(2000) + centrality scoring to a useful ~2910-token capsule in 4.9 s; an unscoped tg search degrades gracefully instead of hanging — it returns a partial result with an honest "exceeded timeout" incomplete_reason and exits 124 (the #400 native-walk deadline doing its job, not a new mechanism); tg inventory --deadline bounds correctly per-project. See §2 below for the one known-open edge this same dogfood surfaced.

0. When to use this skill — and when to use a sibling instead

Use this skill when the task is bounding/honesty at scale: a hang, a --deadline overrun, task #52, the #390 daemon gap, the exit-code partial contract, or a latency profile of a graph command on a big repo.

This skill never routes around change-control. It produces the evidence; the flip is a tensor-grep-change-control decision (Phase 4).

1. What already shipped (verify each before you build on it)

The P0-6 "moat" deadline program (#384-#401) + the now-shipped unscoped-hang fix (#400, #413, #428, #702). Every anchor below is at HEAD on 2026-07-24 (v1.96.0); re-verify line numbers, they drift — main.py is 17032 lines and repo_map.py is 18752 lines as of this pass, do not trust an older total. Both files grew substantially (repo_map.py by ~1850 lines) across the Java/C#/PHP language-support campaign (#719-#726) landed since the last full citation pass at v1.93.2 — several anchors below drifted by 1000+ lines and have been re-pinned in this pass.

| tg find (v1.77.0, #189, main.py:4728-4837, was :4574-4676, drift +147 lines) — whole-repo hybrid NL search, a NEW command that reuses this campaign's bounding shape from day one rather than retrofitting it later | Takes --deadline/--max-repo-files plus an internal corpus-wide chunk cap (_FIND_CORPUS_CHUNK_CAP); a truncated scan sets result_incomplete=true and exits 2 (found-but-truncated prints results THEN exits 2 -- same "truncation trumps found" rule as #401 below, not the found-exits-0 shape #399 walked back). Unlike tg search, tg find does NOT get the instant vendored/workspace-root refusal (#400) -- it always attempts the bounded scan rather than refusing outright, because ranking the whole repo (not raw-text matching it) is the command's entire point. | tensor-grep-run-and-operate §11c has the full exit-contract prose; grep -n "^def find" src/tensor_grep/cli/main.py → :4721 | | #702 (v1.92.3, A9) -- a 4th unscoped front-door fix alongside #400/#413/#428, closing a gap those three never covered | bootstrap._run_rg_passthrough (bootstrap.py:1337, was :1088, drift +249) -- the plain flag-less search front door that runs before main.py's Typer app is ever reached -- had NO walk ceiling at all until this shipped; the three existing main.py-side refusal guards (#400/#413) never ran for this path. Fixed by adding bootstrap._search_paths_include_oversized_implicit_root (bootstrap.py:1053, was :804, drift +249, the same-size shift as _run_rg_passthrough above -- consistent with one insertion earlier in the file), gated on paths_defaulted, sharing the SAME IMPLICIT_SEARCH_WALK_FILE_CEILING = 1500 constant (io/scan_limits.py:106, re-verified exact this pass, re-exported via io/directory_scanner.py) the other 3 doors already used -- natively reproduced, not a WSL artifact. An over-ceiling implicit root now refuses in ~1.7s instead of silently walking up to the 60s TG_RG_TIMEOUT_SECONDS backstop. | grep -n _search_paths_include_oversized_implicit_root src/tensor_grep/cli/bootstrap.py; grep -n IMPLICIT_SEARCH_WALK_FILE_CEILING src/tensor_grep/io/scan_limits.py |

Merge/release state to stamp every session: #400/#413/#428/#702 are all in the installed binary as of v1.96.0 — this is not a source-only or in-flight fix. If a future session finds a NEW in-flight PR referenced by this skill, do not describe it as shipped until git log --oneline origin/main | head shows a chore(release) commit above it (see the project's merge-gate guardrail: an open PR is guidance, not a receipt, until it lands on main).

2. Still open (the campaign's actual work)

• #52 — end-to-end deadline ineffective on a large TS repo — CLOSED by PR #478 (67f9779, shipped v1.54.3). See the shipped-table row in S1 for the four loops it bounded (A: file-tree walk, B: _relevant_tests_for_symbol, C: build_symbol_impact_from_map, D: string_refs second pass). This supersedes the likely-closed framing this skill previously carried after #396/#440/the CALLER_SCAN_FILE_CEILING chokepoint alone — those three narrowed the gap but a verify-plan-against-code pass still found the four loops above live and unbounded; #478 is the commit that actually closes it. Still do a one-time fresh Phase-0 re-measure on a real large TS repo before citing a specific wall-clock number in a benchmark claim or PR -- "the mechanism is closed" and "I have re-confirmed the number on my reference repo" are different claims; S3 Phase 0 gives the exact command.
• #390 — daemon-path deadline gap — CLOSED (task #203, shipped #647/#652/#653, v1.81.2-.4). This was framed OPEN in earlier passes of this skill — that framing is now STALE and risks a future session re-implementing already-shipped code. Verify directly rather than trusting either framing: session_store.py (the daemon's request-dispatch module) now threads a real deadline_monotonic value into its build_symbol_impact_from_map (session_store.py:1449, was :1276, drift +173) and build_symbol_callers_from_map (session_store.py:1490, was :1317, drift +173) call sites — the code comment at session_store.py:1484-1488 (was :1311-1315, drift +173) states explicitly: "the exact #390 daemon-path shape this task (#203) closes." The same threading was extended to refs/blast-radius/file_importers (search session_store.py for WARM_DAEMON_DEFAULT_DEADLINE_SECONDS to see every site). A daemon-served graph query on a cached session repo_map is now bounded the same way a fresh CLI invocation is — the #478 design doc's explicit "session/daemon territory out of scope" carve-out from Candidate (c) below has since been executed as its own follow-up, not left open. Candidate (c) below is retained as the historical solution-menu entry that predicted this fix's shape, not as an open task — do not re-propose closing #390 as new work.
• Default budget. The native-walk bound reuses configured_ripgrep_timeout_seconds(), which now defaults to 60 s (subprocess_policy.py:75, confirmed exact this pass, was 600 s). AGENTS.md:480 (was :378, drift +102 -- grep -n "hangs ~600 s then errors" AGENTS.md) still narrates the pre-#400 "600 s" symptom — that doc lags; the resolver is the source of truth.
• NEW (surfaced by the 2026-07-23 c:/dev dogfood receipt above) — a pathological workspace-union root can still blow an inventory --deadline budget, even though #478 bounded _iter_repo_files's walk. tg inventory always calls build_inventory with an explicit integer max_files (default DEFAULT_MAX_INVENTORY_FILES = 50_000, cli/inventory.py:42/188 — was :40/186, both +2 lines, never None), so _iter_repo_files (grep -n "^def _iter_repo_files" src/tensor_grep/cli/repo_map.py -- :1183 as of 2026-08-14, was :1144) always takes its if max_files is not None: branch (grep -n "if max_files is not None:" src/tensor_grep/cli/repo_map.py -- :1209 as of 2026-08-14, was :1170), whose FIRST step is a single blocking list(os.scandir(normalized_root)) (grep -n "list(os.scandir(normalized_root))" src/tensor_grep/cli/repo_map.py -- :1211 as of 2026-08-14, was :1172) with no deadline check before or during that one call — the per-bucket deadline_monotonic check (grep -n "loop A" src/tensor_grep/cli/repo_map.py -- :1256-1260 as of 2026-08-14, was :1220-1221) only runs AFTER this initial top-level listing has already fully materialized. On an ordinary repo this is instant; on a workspace-union root whose TOP LEVEL itself fans out to a huge number of entries (e.g. a parent folder of many independently-cloned projects, not a normal nested tree), that single scandir() call can burn the whole --deadline budget before any check runs. Triage: rare, and NOT worth a load-bearing fix right now — the fix (a lazy/incremental os.scandir iterator instead of list(...)) would touch a hot, heavily-profiled walk path for an edge case that only bites an already-discouraged usage (scanning a multi-project workspace ROOT instead of a package root; tg orient / tg agent already advise narrowing via suggested_scope/workspace_root_detected, see docs/CONTRACTS.md). Do not silently re-open this as a new #52 — it is a narrower, already-diagnosed gap in a single branch of one function, not an end-to-end unbounded pipeline.

3. The phased runbook (decision-gated)

Run in order. Each gate states the expected observation and where to branch. PowerShell is the dev-box shell; uv run is cross-platform. Use uv run --no-sync so a bare uv run does not re-sync away the [dev] tree (tensor-grep-build-and-env).

Phase 0 — Reproduce the baseline on a REAL large repo (NEVER skip)

You cannot claim "bounded" without the unbounded number, and you cannot claim a fix without the pre-fix number. Use a public large TS repo so this is reproducible (never a private customer path).

# thousands of .ts files, deep import graph — a public customer-scale proxy
# (any large TS repo works; substitute one with >~1500 .ts files if you prefer)
git clone --depth 1 https://github.com/microsoft/TypeScript C:\tmp\ts-ref
$repo = "C:\tmp\ts-ref\src"

# Wall-clock the bounded command against its own budget (source or the installed >=v1.40.4
# binary both have #400/#440; either works, source keeps you at HEAD for a just-landed fix):
Measure-Command { uv run --no-sync python -m tensor_grep callers $repo Node --deadline 10 --json | Out-Null }

Expected + gate:

• GATE 0 (the #52 test): total elapsed should be <= deadline + ~10% (i.e. ~11 s for --deadline 10). Read the JSON: partial/result_incomplete must be true iff the scan was actually truncated, and a truncated result must carry a non-empty incomplete_reason/caveat.
• If elapsed >> deadline (e.g. 25 s for a 10 s budget) -> a NEW regression, not #52 reopened, and not #390 either -- #52 is CLOSED at HEAD (#478/67f9779, S1/§2), built specifically to prevent exactly this shape across all four loops (A/B/C/D), and #390 (the daemon-path gap) is ALSO CLOSED (task #203, S1/§2 above) -- a session-served query is bounded the same way a fresh CLI one is now, so do not reach for "still-open #390" as the explanation. A live overrun here means a new unbounded loop was introduced since #478/#203; if you can reproduce it specifically on a session-served/daemon query and NOT on a fresh CLI one, that is a fresh, narrower finding (a regression in the #203 threading), not a reopening of #390 itself. Proceed to Phase 1 to find where the budget leaks.
• If elapsed is bounded AND truncation is honestly flagged -> matches the current expectation (§2: #52 closed). Do NOT just declare victory: re-run on a second large repo and a central symbol (highest fan-in), confirm the exit code matches docs/CONTRACTS.md:157 (was :156, drift +1; exit 2 fires on ANY truncation, found or not — §5), then route promotion of the "closed" claim through Phase 4 / change-control.
• If it HANGS (no return, no error) on an unscoped tg search on a root with a vendored dir -> this is a NEW bug, not the old #400 shape: #400's instant refusal (_should_refuse_unbounded_vendored_root_scan, exit 2, <1s) plus the native-walk deadline are shipped in the installed tg binary (>=v1.40.4) as well as source, so a hang here on EITHER means the fix regressed -> tensor-grep-debugging-playbook.

Phase 1 — Phase-instrument the ACTUAL slow command (do NOT guess)

Profile the command Phase 0 flagged, on the same repo. cProfile is the oracle here (the graph commands do not all expose --profile; only context-render and blast-radius-render do — verified against tg --help). This invocation is verified to run and print stats:

# tottime = internal (self) time -> finds the true hot function.
# tg's own output prints first; the profile table is APPENDED at the end -> tail it.
uv run --no-sync python -m cProfile -s tottime -m tensor_grep callers $repo Node --deadline 30 2>&1 | Select-Object -Last 30

Expected + gate (verified shape on a real repo): the top tottime rows are the per-file parse — on Python targets {built-in method builtins.compile}, ast.walk, and repo_map.py:2127(_python_imports_and_symbols) (was :1921, drift +206); on TS targets the analog is the tree-sitter parse via repo_map.py:2271(_typescript_parser) (was :2065, drift +206) — invoked many times, because build_symbol_callers_from_map re-parses candidate files in its any()-loop (repo_map.py:3639 documents the "N definitions -> N re-reads/re-parses" hazard, was :3407-3409, drift +231 — grep -n "N definitions means N re-reads" src/tensor_grep/cli/repo_map.py).

• GATE 1a — caller-scan re-parse dominates (many parse calls, high ncalls on the parse/resolve functions): the leak is the re-parse loop, not the one-shot map build -> Solution menu candidate (a) or (b) in Phase 2.
• GATE 1b — a single build_repo_map pass dominates (parse called ~once per file, not per definition): the map build itself is the cost -> the fix is bounding/caching build_repo_map, which #384-#388 already partly did via deadline_monotonic; re-measure whether the deadline is honored INSIDE that pass -> different branch -- a NEW gap, since #390 (the daemon-path deadline gap) is CLOSED (S1/§2 above), not an open "#390 gap" to attribute this to.
• GATE 1c — resolve() / path work dominates despite #396: the cache is being defeated (e.g. an uncached resolve() before the cache lookup — repo_map.py:2712 warns about exactly this, was :2506-2507, drift +206 — grep -n "this resolve() runs BEFORE the re_export_cache lookup" src/tensor_grep/cli/repo_map.py) -> candidate (b), fix the cache ordering.

Redundancy measurement before you design a cache (candidate b obligation): monkeypatch the parse function with a collections.Counter keyed by path and count how many times each file is re-parsed for one callers call. This is the technique that overturned a code-review guess in PR #345 (see fenced paths). Numbers first, then design the key.

Phase 2 — Solution menu (RANKED), each with a proof obligation

Pick top-down. Each candidate carries an obligation you must verify/measure, not assume, before building.

Candidate (a) — bound the caller-scan re-parse loop (preferred)

Apply the same per-file deadline check #400 used for the native search walk to the caller-scan any()-loop: check native_walk_deadline_exceeded (or an equivalent deadline_monotonic) once per file, and on expiry break to a partial.

• Obligation: the partial must be fail-closed and flagged — set result_incomplete = True + a concrete incomplete_reason, and let _emit_symbol_command_result (grep -n "^def _emit_symbol_command_result" src/tensor_grep/cli/main.py -- :11722 as of 2026-08-14, was :11762 at the 2026-07-24 pass, was :11298 before that) apply the exit contract: per §5, ANY truncated/partial result exits 2, regardless of whether it's empty or non-empty (#401 — do not build toward the old #399 "found-but-capped exits 0" shape). Mirror #400's shape (main.py:8137-8270, was :7979-7992): break, never return a clean empty.
• Why preferred: it directly closes #52 with a mechanism already proven in-tree; low blast radius; deterministic. This is what #478 (67f9779) actually shipped -- the same per-file-deadline-check shape, applied to all four residual loops (S1/S2). This menu entry stays useful as the template for the next #52-shaped finding, not just a historical proposal.

Candidate (b) — extend the #396 caching to the residual re-parse

If Phase 1 shows re-parses that #396's caches miss, widen coverage.

• Obligation — cache-key correctness: a repo-map cache MUST key on file mtime+size (use the existing _mtime_aware_cache (grep -n "^def _mtime_aware_cache" src/tensor_grep/cli/repo_map.py -- :108 as of 2026-08-14, was :100), not a plain lru_cache keyed on path alone — a plain cache returns stale results in the long-lived daemon (the code comments at repo_map.py:30-34 + the _MTIME_CACHE_CLEAR_REGISTRY declaration (grep -n "^_MTIME_CACHE_CLEAR_REGISTRY" src/tensor_grep/cli/repo_map.py -- :64 as of 2026-08-14, was :55) document this trap and the sweep). Prove the redundancy with the Counter-monkeypatch (Phase 1) BEFORE adding the cache, and prove correctness with a mutate-file-then-re-query test.
• Caching bounds the common case but does not bound a pathological single file — ship it WITH candidate (a), not instead of it.

Candidate (c) — close the #390 daemon-path deadline gap — SHIPPED (task #203, #647/#652/#653, v1.81.2-.4); retained here as historical record, not an open candidate

This entry correctly predicted the shape of the eventual fix and is kept for that reason, but the work itself is DONE — do not re-propose it as new. What actually shipped: session_store.py's daemon call sites (build_symbol_impact_from_map at session_store.py:1449, was :1276, drift +173, build_symbol_callers_from_map at session_store.py:1490, was :1317, drift +173, plus refs/blast-radius/ file_importers siblings) now pass a real deadline_monotonic value (WARM_DAEMON_DEFAULT_DEADLINE_SECONDS-derived) into every builder call — exactly the call-site wiring this candidate originally scoped as the remaining work after #478's builder-side prerequisite. See S2 above for the closing citation (session_store.py:1484-1488's own code comment, was :1311-1315, names task #203 as the closer). If a NEW daemon-served command is added in the future, use this shipped pattern as the template — thread deadline_monotonic at the call site, mirroring the sibling commands in the same file, rather than assuming the daemon path is unbounded by default going forward.

Candidate (d) — replace the regex/slow TS parse with tree-sitter (HIGHEST RISK — fenced)

Only if (a)+(b)+(c) leave the parse itself as the irreducible hotspot.

• Obligation (mandatory, before any swap): golden parity across the parser corpus. A parser change alters symbol/import extraction for every downstream command; prove byte-identical (or explicitly-diffed-and-accepted) output on the AST parity corpus first (benchmarks/run_ast_parity_check.py). Do this in a fenced branch; do not mix it with a bounding fix.

Phase 3 — Build behind the fail-closed contract + measure the gate

• Write the failing test first (tests/unit/test_repo_map_targets.py, tests/unit/test_cli_modes.py are the patterns #400 used). TDD, then the smallest fix.
• Honor the Backend Fail-Closed / partial contract (§4): a bound that trips produces a flagged partial, never a silent empty, never a raw crash.
• Re-run Phase 0 + Phase 1 on the reference repo after the fix.
• A6 — anti-hang test discipline (a hang-class regression test can itself hang): when the red test is "this used to hang/overrun," wrap it so a still-broken fix fails FAST instead of wedging the test run. (1) layer an OUTER shell timeout (--kill-after=Ns) around an INNER per-test timeout implemented via a thread/watchdog, not signal (signal-based timeouts are a no-op on Windows and under the GIL for CPU-bound native calls — this repo runs CI and dev on Windows). (2) either land the fix before the red test lands, or land the red test already wrapped in both timeouts. (3) never leave an unbounded loop/subprocess-spawn/backtracking regex in the TEST ITSELF without its own bound — the test must fail the same way the product bug does (bounded, flagged), not hang the CI runner. (4) distinguish "slow but protected" from "hung" by EXIT CODE (124/137 = killed) not elapsed wall-clock, which is noisy on a shared runner. (5) apply the same two-layer timeout in CI as locally — a hang that only reproduces in CI because the outer timeout was dev-box-only is the worst kind to debug.

Promotion gate (all must hold, measured on the reference repo, same symbol):

• GATE 3: if the wall-clock still overruns the budget OR a partial isn't flagged, do not ship — the honesty contract is the whole point. Iterate or record the negative result.

Phase 4 — Promote through change-control (never here)

This skill produces evidence; tensor-grep-change-control owns the flip.

1. One release-bearing PR per tick (respect the push-race / one-merge-per-tick rule, tensor-grep-release-and-positioning).
2. Attach Phase 3 evidence (before/after wall-clock table + exit-code proof + parity).
3. Re-dogfood on the REAL large repo before declaring the contract done — this is the #399 lesson: #398 shipped an exit-code rule that had to be walked back one release later because the real-repo behavior (every large-repo query exiting 2) was wrong.
4. Update docs/CONTRACTS.md / AGENTS.md / SESSION_HANDOFF.md if the contract changed (tensor-grep-docs-and-writing).

4. Fenced-off wrong paths (do NOT do these)

5. The contract you are defending (exit codes + fail-closed)

Symbol-command exit codes are a 3-state agent contract (docs/CONTRACTS.md:157, was :156, drift +1, enforced at main.py:11639-11832, was :11054-11099, drift +708 — grep -n "^def _emit_symbol_command_result" src/tensor_grep/cli/main.py). This is the current, FINAL shape — #401 reverted #399, so exit 2 fires on ANY truncated/partial result, whether or not it found something:

Do not describe a "found-but-scan-capped result exits 0" behavior anywhere — that was #399, walked back by #401 after a unanimous design council concluded truncation must always trump "found something," so a caller/blast-radius consumer can never mistake a capped result for a complete one. The native-walk bound (#400) is the search-side analog: on expiry it sets all_results.result_incomplete = True + incomplete_reason, writes a stderr warning, and breaks (main.py:8137-8270, was :7979-7992) — a flagged partial, never a silent empty. Any new bound you add MUST follow this shape (see tensor-grep-architecture-contract for the full BackendExecutionError contract).

tg find (v1.77.0, #189) followed this shape from its first shipped version — a genuine example of a new command adopting this campaign's contract instead of retrofitting it: any --deadline/--max-repo-files/internal chunk-cap truncation sets result_incomplete=true and exits 2, whether or not ranked matches were found. It is bounded but NOT refusal-gated the way tg search is (#400's instant vendored/workspace-root refusal does not apply) — see the §1 shipped table.

6. When NOT to use this skill

• A hang/slowness whose cause you don't yet know — do the systematic bisection in tensor-grep-debugging-playbook first; come back here once it's

…(truncated)