feat(pilot): show the LLM the relevant parts of large files, not just the head - #4

Problem

The Pilot only ever showed the LLM the top of each file.

• The Patch Writer read each candidate from line 1 and stopped at 400 lines / 12k chars. The shared 16k-char budget was handed out first come, first served, so a large first file took 12k, the second got about 4k, and files 3 to 5 were usually (omitted — prompt size budget reached).
• The applier only accepts an edit whose search text matches the file exactly. If the bug sits below the cut (say line 900 of a 1,000-line file), the LLM never sees it and can't write a matching search. The Reviewer then spends all its attempts and the run ends rejected, whatever the model.
• The Code Explorer's rerank snippets had the same blind spot: the first 50 lines of each file, usually imports.

Change

New app/agents/_shared/excerpts.py (pure functions, no LLM or network):

• A file that fits its budget is kept whole, so nothing changes for small files.
• Otherwise it keeps the file head plus windows around the lines that mention the issue's keywords. Keywords are weighted 1 / (lines containing them), so reset_token outranks user. Each window brings its enclosing def / class / function lines.
• Each skipped stretch becomes one marker line: ... [lines 120-480 not shown] .... Shown lines are verbatim, so search text copied from an excerpt still matches, including CRLF files (same universal-newline read as the applier).

Patch Writer

• The 16k budget is split across candidates by Explorer confidence (water-filling), so small files stay whole and large ones share the rest.
• On a retry, lines named in the previous failure (File "x.py", line N, x.py:N) are shown first, so the model sees the code its SyntaxError points at.
• The system prompt explains the marker and says never to put it in search.
• _read_file_for_prompt and _MAX_FILE_LINES are removed. The char budgets (_MAX_FILE_CHARS, _MAX_TOTAL_FILE_CHARS) are unchanged, so prompt size and free-tier TPM limits are unaffected.

Code Explorer: read_snippet(..., keywords=...) builds the same kind of excerpt within the same 50-line budget. Without keywords it still returns the head of the file.

Before / after

The three end-to-end prompt tests fail on main and pass here:

Selecting excerpts takes 23 to 39 ms on a 5,000-line, 170 KB file with a match on every 7th line.

Tests

• 34 new tests: tests/test_excerpts.py (budgets never exceeded, verbatim lines in place, rare-keyword ranking, enclosing headers, anchors, CRLF) and additions to tests/test_patcher.py and tests/test_explorer_scanner.py.
• Full suite: 550 passed, 2 skipped (Docker). The 8 failures in tests/test_pilot_api.py also happen on unmodified main without an LLM key (503 from get_llm_router).
• ruff check is clean on the changed files.