Skip to content

feat(files): search file contents from the side panel, documents included - #10756

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/sidepanel-content-search
Sep 16, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/sidepanel-content-search

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

The chat side panel's Files tab can only search file NAMES. To find which file
mentions a string, you open files one at a time. And the text inside a Word,
PowerPoint or Excel document cannot be searched from the dashboard at all — the
name is all the panel can see.

Why it matters

Finding where a string lives is a constant task, and the panel makes you do it by
hand. Documents are worse: a rate limit written into a spreadsheet and a decision
made on slide 7 are invisible, so the panel quietly answers "not here" about text
that is right there.

What changed (motivation → approach → change)

You can now search file contents from the Files rail, documents included.

A Name / Content toggle, in words, sits on its own row under the search
field. Name is unchanged and still the default. Content asks the gateway which
files CONTAIN the text and lists them: root-relative path, :line, and the
matching line with the match marked. Clicking a text hit opens the file at that
line, through the reveal path the panel already has; clicking a document hit
opens the file at its start, because a document has no line to reveal.

Both extractor loops are bounded by the shared DEADLINE, not only by the
character cap, because the cap bounds text and not work. A crafted workbook whose
sheet is millions of EMPTY rows passes the zip-inventory vet as one small member,
yields no text, never reaches _GREP_DOC_MAX_CHARS, and would iterate every row.
So the worksheet row loop samples the clock every _GREP_ROW_DEADLINE_STRIDE rows
— a stride, because a clock read per row is pure overhead on a legitimate large
sheet, and the stride still bounds the overshoot to a fixed row count rather than
to the file's size. _grep_doc_segments
returns (segments, whole), and a parse that did not see all of a document's text
— deadline, mid-read failure, or the character cap — marks the answer partial.
.docx/.pptx have no loop for the deadline to cut; their text is requested one
character past the cap so a cut at the cap is detectable.

There is no extraction cache. An earlier revision kept an LRU keyed by a digest of
the bytes; it needed a cacheable flag beside whole, carried the partial-parse
flag through the cache, and drew three rounds of findings for 14 lines of code.
The shared 2 s budget already bounds what one keystroke can cost, so documents are
re-parsed per request.

The sensitive-path globs are ANCHORED under the search root, which is what keeps
that optimisation from being a divergence. is_sensitive_path — the declared
authority, applied per hit by both engines — is HOME-anchored: ~/.npmrc is a
credential store, a project's own .npmrc is an ordinary file, and the python
walk searches the latter. An unanchored !**/.npmrc excluded it at any depth, so
the same query answered differently depending on whether the host had ripgrep,
with the rg host quietly returning less. Each entry is now resolved to its
absolute home path and emitted only when it truly lies inside the tree being
searched, as a root-ANCHORED glob. The leading slash is what anchors it:
ripgrep follows gitignore semantics, under which a pattern containing no slash
matches a BASENAME at any depth, so a bare !.ssh would hide every .ssh in the
tree — the same unanchored behaviour, reintroduced silently. A root outside HOME
emits nothing and loses nothing: there is no credential store under it for the
glob to have saved a read on. A test states the parity over the pair — no exclusion the argv carries may
hide a name the python walk would search under the same root.

The status row names the UNIT. Every engine returns at most one row per file --
--max-count 1 for ripgrep, a break after the first matching line in the python
walk, one segment per document -- so a bare "7 results" beside seven single-line
rows left it open whether a result was a file or one spot inside a file, and under the second
reading the list looks like it is hiding the other matches in each file. The row now
adds "one row per file", and only when there are results, since nothing found needs
no description. The count itself is unchanged: components.discoverySearchBar.result
is shared with two other surfaces and registered in pluralKeys.json, so relabelling
it to "8 files" would have meant either changing all three or minting a new plural key
across eleven plural systems. Naming the unit beside the count answers the ambiguity
without either.

Previous hits are kept only WITHIN a project. placeholderData keeps the
last answer on screen so that refining a query narrows a visible list instead of
blanking it for the debounce plus the whole 2s budget — but the query key carries
the project directory too, so keeping it across every key change also kept it
across a PROJECT switch. Each row opens by absolute path, so those rows stayed
clickable and opened a file from the project the user had just left. The
placeholder now returns the previous answer only when the previous key names the
same project; a different project's answer is not an approximation of this one.

The status row's tooltip names the CONSEQUENCE, not the engine. "Searched with
python." reads as a claim that the search was narrowed to Python files, which is
the misreading the code comment already predicted; and the fast path needs no
gloss at all. So the tooltip appears only when the host took the slow path, and
says that this host has no ripgrep and the search used the slower built-in scan.

A document row carries NO hover tooltip. The tag beside the file name
(slide 7, Costs · row 12) is the whole of the row's own location information,
and the always-visible note above the list explains that a document opens from its
start. That note leads with what the tag IS and treats Word as the exception, rather
than opening on a condition: a blind reader parsed the condition-first wording only
tentatively ("I think it explains the tags, but I'm not certain"). It now reads
"…the tag after its name says where the text was found — a slide, or a sheet and
row. A Word file has no such place, so it shows no tag." The empty state reads "No
results" rather than "No matches", so it no longer sits two words apart from the
"0 results" count directly above it.

That note no longer promises a tag unconditionally: it
previously read "the tag after the file name shows where the text was found",
which made a tagless .docx row look like an anomaly — the reader could not tell
whether it meant the file's position was unknown. It now says a tag appears when
the format has a place inside it to name, which is the truth for all four
formats. A title on that tag restated both, and being gated on the
tag existing it was absent from exactly the row a reader most wanted it on -- a
.docx hit, which has no location inside the file to name and therefore no tag.
So the tooltip is gone rather than extended: one always-visible explanation, and
no row that is the odd one out. A test pins that no row carries the title and
that the visible note is still rendered.

One EXISTING control changes behaviour, which is worth stating plainly rather
than leaving to the test list: the All/Changed segment is HIDDEN while Content
mode is active, and returns untouched when the mode goes back to Name. It
filters the tree by git status, and searching the staged-changes list is an
explicit non-goal of this PR, so in Content mode it would either mislead or do
nothing. Disabling it instead was rejected: a disabled segment keeps its active
highlight, so it would still assert that a filter was in force. Hiding it does
not reset a Changed selection — the selection survives and is honoured again
when the tree returns, and a test pins exactly that.

POST /api/file-grep with {root, q} in the body answers it -- a POST, because the query is secret-class text and a request URL is what proxies and access logs retain. A text pass runs rg --json where the
host has ripgrep and an equivalent python walk where it does not. The two are one
contract, so ripgrep is pinned to the fallback's semantics rather than its own
defaults: --fixed-strings (the fallback matches a literal, so a.c is three
characters and config( is a search, not a regex parse error), --ignore-case
(the fallback folds case unconditionally), --no-ignore (os.walk cannot
honour .gitignore, .ignore or .rgignore), --max-filesize (the fallback
skips a file over 2 MB, so ripgrep must too) and --max-count 1 (the rail lists
files, not occurrences). The query is not in the argv. A child's arguments are readable by other
accounts on the host through /proc/<pid>/cmdline and ps, and this handler
already treats the query as secret-class text -- it redacts it before every SEL
write, because "which file holds this key" is an ordinary reason to type a
credential into a search box. Putting it on the command line published it to the
whole host for the life of the process, contradicting the redaction two functions
away. --file - hands the pattern list over stdin instead, which is the channel
cron_script.py already feeds through the same sandbox launcher and
popen_limited. It also retires the argument-terminator question by
construction: a query starting with - cannot be misread as a flag when it is
not on the command line to be read.

One INPUT RULE follows from that channel and is worth stating because a user can
hit it: a query containing a line break is answered empty. --file is
line-delimited, so a two-line pattern file would be two patterns OR-ed together,
while the python pass matches one literal -- the engines would answer different
questions. It joins the existing length bounds rather than earning an error code
of its own, because the answer is the same one a one-character query gets and it
is the TRUE answer either way: both engines are line-oriented, so a pattern
spanning a newline matches nothing. Trailing whitespace is still just trimmed, so
a query pasted with a newline on the end searches normally.

The argv exposure fix is deliberately scoped to this endpoint; the app
sibling is deferred.
apps/builtins/file_explorer/server.py still passes its
user-typed query as an argv element (cmd += ["--", ...]), so the exposure this
section describes is still open there. That is a conscious scope decision, not an
oversight: the harm is general — process arguments are readable by other accounts
on any host — but the two searches run behind different authorization models (that
app enforces ALLOWED_ROOTS in a separate process; this handler enforces
_validate_dashboard_path + is_sensitive_path inside the probe pool), so
changing its spawn means changing its trust boundary from a PR about the chat
rail's file search. It is recorded on #10852 with both carry-overs named — the
--file - channel plus the line-break refusal that channel requires, and
validate_provider_executable for its still-unvetted binary — so the follow-up
starts from two known one-line calls rather than a rediscovery. A reviewer who
thinks a general-harm finding must be fixed at every call site inside the PR that
names it should say so; that is a scope call, and this paragraph exists so it is
made against a stated position rather than a silence.

The ripgrep it runs is vetted first, by the repo's existing
executable-provenance chokepoint rather than by a rule of this module's own:
github_runner.validate_provider_executable, the same function gh, glab,
az, aws and the terminal panel resolve through. It refuses containment in
the agent-writable project or workspace tree, ownership by a third account,
world-writability anywhere in the parent chain, a symlink chain, a non-regular
or non-executable file, a root gateway, and on Windows reads the real ACL
where the mode bits carry no information; KIROCREW_PROVIDER_BIN_STRICT
escalates it. rg takes the default relaxed policy — it is handed no provider
credentials, so require_protected stays unset and an ordinary Homebrew or
~/.local/bin install keeps working. Any refusal is a fallback, not an error:
the python engine answers the same question. A document
pass then extracts .docx / .pptx / .xlsx.

.pdf is deliberately NOT in that set, and that is the one thing this PR does
not ship.
Extracting PDF text has no memory ceiling this process can enforce:
pdfplumber exposes no length limit, the allocation is the parsed character list
itself, and the aggregate character cap is evaluated only after a page is
appended — so a SINGLE page is unbounded, and a 25 MB input can decompress to
orders of magnitude more text. Without the extension a PDF is not a document to
this pass, and both engines then skip it as binary (ripgrep by its own detection,
the python walk by its NUL sniff); test_a_pdf_is_not_searched_at_all pins that
with a .docx beside it, so the assertion cannot pass by finding nothing.
Restoring it needs a resource-bounded extractor, and that belongs with the
identical exposure in knowledge/readers.py:_read_pdf rather than here alone —
tracked in #11052.

Symlinked FILES are skipped by both engines. ripgrep does not follow symlinks
while traversing, so a link to a matching file is invisible to it, while
safe_read_prefix read it happily — one tree answering differently depending on
whether the host had ripgrep. The sharper half is containment: a link can point
anywhere, so the python walk was reading bytes from outside the root the caller
named (verified — a link to a file in a sibling directory was returned as a hit).
os.walk already declines to DESCEND into a linked directory, so this is the
file-shaped half of a rule the directory half already followed. Both engines are
asserted on the same tree, with an ordinary file beside the link so the test cannot
pass by finding nothing.

Both passes share one 2s budget, and the answer says whether it was partial and
how many documents the budget did not reach, as a floor — so "no matches" and "the
search stopped" stay different facts. ripgrep's records are read INCREMENTALLY
and the child is stopped at the 200-result cap: --max-count 1 bounds records
per file and --max-filesize bounds one record, but neither bounds how MANY
files match, so buffering the whole output to keep the first 200 grew with the
workspace. Streaming also makes a timeout's partial answer simply "what the
reader parsed", because the deadline is shared and the fallback would start with
nothing left.

A document row shows WHERE inside the document it matched instead of a line
number, because none of those formats has one: slide 7 or Sheet1 · row 12. A
Word file shows NO tag: its paragraphs carry no page or section to name, and doc
beside a .docx filename added nothing the filename had not. That tag is a LABEL, not a jump target, and the visible line above
the list says so in the reader's own terms -- "the tag after the file name
shows where the text was found", not "the badge", which named nothing on
screen. Jumping a document hit to its slide or row is deliberately out of scope
(see the non-goals in the intent comment), so revealLine keeps one meaning -- a
source line -- everywhere.

Guards bound what the response and the audit trail can carry. The root goes
through the same _validate_dashboard_path / is_sensitive_path chokepoint
every other file handler uses. Every document is read once through
safe_read_prefix, which identity-checks the descriptor, and parsed from those
bytes, so no parser can reopen a swapped path. Every preview is redacted at the
single row builder both passes share — a search returns the matching LINE, so a
key pasted into ordinary source would otherwise travel with it — and the query
goes through the same redactors before it reaches the SEL log. A workbook is
refused before openpyxl loads if its declared members expand past the sheet endpoint's 200 MB
ceiling.

What you type it against Before After
A file name 🟦 found in the tree 🟦 found in the tree
Text in a .py / .md file 🟥 not searchable 🟩 found, opens at the line
Text in a .pptx 🟥 not searchable 🟩 found, row says slide 7
Text in an .xlsx 🟥 not searchable 🟩 found, row says Sheet1 · row 12
Text in a .docx 🟥 not searchable 🟩 found, no tag — nothing inside to name
~/.aws/credentials under the root 🟦 never listed 🟦 never read
Text in a .pdf 🟥 not searchable 🟥 still not searchable — see #11052

🟩 added · 🟨 changed · 🟥 removed · 🟦 unchanged

Not a product-shape change: Name stays the default, nothing is removed or
replaced, and no existing default moves — so no RFC under
docs/request-for-change/ applies.

Where the code lives:

Area What it holds
src/kiro_crew/dashboard/handlers/files.py api_file_grep, both engines, the document pass and the caps
src/kiro_crew/dashboard/handlers/__init__.py, src/kiro_crew/dashboard/routes/taskrunner.py the export and the route, beside /api/file-search
docs/feature-map/README.md the Files-in-chat row now names the toggle, the document formats and /api/file-grep
website/src/api/fileGrep.ts the typed client, requesting through the blessed apiTransport so a lapsed session raises the auth banner
website/src/pages/chat/FileBrowserRail.tsx the toggle row, the debounce and the results list
website/src/pages/chat/SidePanel.tsx, website/src/pages/chat/FilesHomePanel.tsx thread a hit's line to the panel that reveals it
website/src/i18n/locales/ ten keys in en.manual.json and every other catalog; en-XA.json regenerated by npm run i18n:pseudo
test/test_file_grep.py, test/test_dashboard_files_onloop_fs.py, website/src/test/FileBrowserRail.test.tsx, website/src/test/fileGrep.test.ts the tests below
website/capture/files-rail-content-search.*, website/scripts/capture-files-rail-content-search.mjs the screenshot harness that produced the evidence below

Deferred duplication (named, not hidden)

Two places where this change is a SECOND copy of something the repo already has.
Both are deliberate for this PR and neither is silent:

The rg + python engine duplicates src/kiro_crew/apps/builtins/file_explorer/server.py.
_grep_rg/_grep_python here and _search_rg (:749) / _search_python (:868)
there are the same rg-or-python contract spelled twice. Unifying them is deferred
to #10852. What matters more than the tidiness: the parity and trust work is on
THIS side only — --fixed-strings, unconditional --ignore-case,
--max-filesize, timeout-partial recovery, and the absolute-path resolver that
defers to validate_provider_executable. The sibling still spawns a bare rg off $PATH, which is
the substitution vector this copy's resolver exists to close. #10852 leads with
that, and accepts either one shared engine or the same fixes applied to the
sibling. Not folded in here because the two run behind different authorization
models — that app enforces ALLOWED_ROOTS in a separate process, this handler
enforces _validate_dashboard_path + is_sensitive_path inside the probe pool —
and the intent comment names sharing that model as a non-goal.

The PDF page loop that duplicated KnowledgeReader._read_pdf is gone, because
PDF is out of this pass entirely. What remains is worth recording for #11052, which
picks it up: knowledge/readers.py:_read_pdf loops page.extract_text() with no
page cap and no character cap at all — strictly less bounded than the copy deleted
here — and its per-page try has no except, so one raising page discards every
page already read. Both call sites want the same resource-bounded extractor, which
is exactly why that work is not in a file-search PR: fixing one and leaving the
other is the point-patch shape this PR has been told off for more than once.

Tests

test/test_file_grep.py — 55 tests in eight groups.

Gating: a sensitive root and a validator-refused root are both 403 (not 404,
which would invite probing for an allowed spelling), a file root is 404, a
one-character query is not a search, and a sensitive hit is dropped by EITHER
engine.

Engine parity, which is where the round's real work is. Both engines are compared
against each other on one tree — same files, same lines — and then each divergence
gets its own case: a literal query (a.c must not match abc), an unbalanced
query (config( is a search, not a parse error), case folding whatever the query
looks like (Widget finds widget), a .gitignored file answering the same on
both hosts, and a multi-byte line surviving intact. The argv itself is asserted
too, so the four parity flags and the all-globs-negated rule are pinned on a host
with no ripgrep.

Budgets: the result cap and a spent deadline both report truncated rather than
an empty list, an rg ERROR exit takes the fallback while exit 1 is accepted as a
real "no matches", a timeout returns its partial hits (decoded from the bytes
CPython actually raises), a file over the size ceiling is skipped by both
engines, the document pass leaves the walk on a spent deadline instead of
counting through the tree, an oversized document is skipped, and a busy probe
pool is a coded 503.

Trust and retention: the resolver hands which's candidate to the provenance
chokepoint and spawns only what comes back, a refusal takes the python engine,
and a secret typed as the query never reaches the audit log. The chokepoint's own verdicts are tested
against real descriptors and real mode bits in test_source_providers.py and
test_windows_acl.py; re-asserting them here is what produced a local subset
that disagreed with it.

Documents: no label for .docx, slide 3 for a deck, Sheet1 row 2 for a
workbook, a .pdf not searched at all (with a .docx beside it so the assertion
cannot pass vacuously), a bloated workbook refused before openpyxl,
no file reported twice, a symlinked document outside the root not read (with a
plain document beside it as the control), and a capped, deadline-cut or mid-read
broken parse each reported as partial.

The rg spawn: a fail-closed sandbox refusal (SandboxUnavailableError, a
RuntimeError) takes the python engine instead of raising into a 500 on a host
with no backend, wrap_argv's launcher temp file is unlinked on every path
including the timeout, and the reader stops at the cap and kills the child
rather than draining a tree it has already answered for. One test gives it a
pipe that never speaks: rg prints nothing for a non-matching file, so a
rare-or-absent query used to run to rg's own completion past the budget and
then report a COMPLETE answer — the read is now bounded by the deadline, not by
when rg chooses to emit a line. Another runs the REAL policy as a control and a variant differing in one bit: a
0755 rg in a private directory clears, and the same file refuses once its
parent is 0777 and not sticky — the case a world-writable test applied to the
binary alone let through, and the reason to delegate rather than re-spell. It
skips where the control cannot clear (an NFS home whose parents stat as the
overflow uid 65534, a root gateway) instead of passing vacuously. A third pins
that a page which fails to extract costs its own page only, not the pages
already read.

The sensitive-path fence runs INSIDE the probe, not on the event loop.
is_sensitive_path is filesystem work whose name does not look like it: one call
resolves the path and walks its ancestors, measuring 72 lstat, 8 realpath, 6
readlink and 2 stat for one ordinary path. Called from the coroutine it parks
the gateway's only event loop on whatever mount the caller named — the same hazard
the ratchet already records for shutil.which. It now happens in
_grep_resolve_root, which the handler reaches only through _run_path_probe,
and an empty root there means REFUSED for either reason (an invalid name or a
credential store) because the endpoint already answered both with the same 403. A
test asserts the placement by thread identity rather than the outcome, since the
403 was correct before and after.

That name is deliberately NOT added to the ratchet's list in this PR: nine call
sites in this module call is_sensitive_path from a coroutine body, eight of them
pre-existing, so the entry would turn a file-search change into a module-wide
refactor. It is worth its own change and the count is recorded here so the
follow-up starts from a number rather than a suspicion.

test/test_dashboard_files_onloop_fs.py — the new endpoint joins the off-loop
ratchet: root validation and the search both run off the event loop, and the
search takes a TRANSFER pool slot, not a probe slot. The ratchet's own name list
gains which, because shutil.which stats every $PATH entry and so is
filesystem work whose name does not look like it. That entry is REPO-WIDE and not
scoped to this endpoint: the ratchet asserts over every guarded handler, so from
this PR forward any handler calling shutil.which on the event loop fails it.
I believe that is correct — a $PATH walk is filesystem work wherever it
happens, and the ratchet exists to catch exactly the calls whose names do not
look like I/O — but it is a tightening other handlers now inherit from a
file-search PR, so it should be a declared consequence rather than a surprise. No
existing handler needed changing for it; the ratchet passes as-is. The suite's requires_rg
marker stays PURE, because a skipif condition is evaluated at COLLECTION and
_grep_rg_executable resolves through the provenance chokepoint — which reads
agent_writable_roots(), hence workspace_root(), which does
mkdir(parents=True). Asking the resolver there made merely IMPORTING the test
module create the operator's real workspace directory (verified directly: a bare
agent_writable_roots() call with a fresh KIROCREW_WORKSPACE creates the
path). So the marker checks shutil.which and a _require_rg_engine() helper
runs the provenance question from the test BODY. Both halves are needed: which
and the resolver disagree wherever the chokepoint refuses a ripgrep that is on
$PATH, and on the marker alone the rg arm of every parity pair would run the
python engine while claiming to cover ripgrep. This matches the repo's own
convention — requires_git and requires_symlinks in conftest are pure for the
same reason.

website/src/test/fileGrep.test.ts — 2 tests for the wire call the rail tests
mock away: /api/file-grep with root and q URL-encoded (a space, &, = and
( all survive), the decoded body returned as-is, a transport error surfacing
rather than shaping an empty answer.

website/src/test/FileBrowserRail.test.tsx — 22 tests: the toggle's default and
its survival across a remount, no request below two characters, one request for a
burst of keystrokes, the tree replaced by the hit list, shortened paths, the match
marked without changing the file's casing, :line versus a location badge, click
routing for a text hit ({ line }) and for a document hit (no line), the status
line's states — count, partial, documents skipped, empty — the engine name kept
to the tooltip, both mode words always visible, a document hit opening from the
start rather than at a line (its slide 3 badge is a label, and the test pins
that no position is routed), the visible note for document hits, and a failure
rendering through ErrorNotice with the agent hand-off rather than as a red
line. Three more cover the tree-mode segment and the in-flight list: All/Changed
is absent in Content mode and returns with the tree, hiding it does not silently
reset a Changed selection, and a refined query keeps the previous hits on screen
instead of blanking the list while the next answer arrives.

Manual verification

The screenshots below are Playwright frames from the real component at rail
width, captured by website/scripts/capture-files-rail-content-search.mjs. The
driver asserts the palette, the document badges and each arm's own visible
state, so a frame that claims a theme, a badge or a status it does not carry
fails the capture rather than shipping. Seven arms per theme: results, the partial
arm, the below-minimum hint, a search that found nothing, a failed request, the
in-flight state with the request held open, and Name mode.

Screenshots / video

Content mode, light and dark: the Name / Content row, four text hits, then two
tagged document hits (slide 7 and Costs · row 12) plus the tagless .docx row,
with the note above the list stating both halves — a text hit opens the file AT its
line, a document hit opens from the start. Saying only the second half is what left
the :42 tag reading as "line? page?".

Frames re-captured at this head, and the embedded images below ARE those captures.
Checkable claims, so a future drift contradicts a specific sentence rather than a
boast: the status row reads "7 results · one row per file"; exactly two rows
carry a tag, slide 7 and Costs · row 12, with no p 3 because PDF is out of
this PR; the document note reads "…a slide, or a sheet and row"; the empty arm
reads "No results"; the in-flight arm reads "Searching…" with no row and no
count; and the tagless docs/decision.docx row is present in the results arm.

Files rail content search, light

Files rail content search, dark

The capped arm, and Name mode unchanged

The status line when the budget stopped the search: 4 results · partial · at least 6 documents not searched. "partial" is the same word the sentence below
the row uses, and the skipped count says "or more" because it is a floor —
documents the budget never opened, not a tally to reconcile against the rows.
The engine name stays in the row's tooltip.

Capped content search, light

Capped content search, dark

The three states a reader meets when the search does NOT return a list, each of
which previously had no frame at all — so "query too short", "ran and found
nothing" and "the request failed" all reviewed as unknown:

Below the two-character floor, no request is made and the rail says so.

Content hint, light

Content hint, dark

A search that ran and found nothing — 0 results and "No results", which is what
distinguishes it from a search that has not run. Both read the same word on
purpose: two different words for one outcome made the reader stop and compare
them.

Content empty, light

Content empty, dark

A coded 503 from the probe pool, rendered through the shared ErrorNotice with
the agent hand-off rather than as a hand-rolled red line.

Content error, light

Content error, dark

The in-flight state: the request held open, so the rail is mid-search — "Searching…" in the status row over the blank list region. This is what a reader sees for up to the 2 s budget on a first search.

Content searching, light

Content searching, dark

Name mode, for contrast — the tree, exactly as before. The All/Changed segment
is here and absent from every Content frame above: it scopes a tree, and Content
mode has none.

Name mode, light

Name mode, dark

Related Issues

Related: #7625 — its first and largest ask, content search in the side panel,
plus the document extraction it expected to inherit from #4648.

no linked issue: #7625 asks for a whole VS Code-style Search view and this is
its first phase, so closing it would drop the rest of what it asks for —
results grouped by file with per-file counts, match-case / whole-word / regex
toggles, include and exclude glob inputs, Cmd/Ctrl+Shift+F, and searching the
staged-changes list. Those are worth their own PRs against the same issue.

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

@iamwhatever
iamwhatever requested review from a team and hoang-phan98 September 14, 2026 10:14
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Sep 14, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Intent: Make the side panel's Files tab able to answer "which file contains this text" — including text inside PDF, Word, PowerPoint and Excel documents, which the dashboard cannot search at all today.

Not a goal: the rest of a VS Code-style Search view (results grouped by file with per-file counts, match-case / whole-word / regex toggles, an exclude-glob input, Cmd/Ctrl+Shift+F, searching the staged-changes list); sharing the Files app's process or its allow-root model; jumping a PDF hit to its page in the viewer.

@github-actions

github-actions Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5) — ✅ PASS

Design-level review of 843a17806b7377b38e63809273632ee51f04c96d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: PASS

Verify #10852 and #11052 actually carry the deferred argv-exposure and bounded-PDF work as described — the design leans on those follow-ups existing.

[DESIGN-REVIEWED] 843a178

@github-actions

github-actions Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5) — 🟡 CONCERNS

Premise-level review of 843a17806b7377b38e63809273632ee51f04c96d — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

First-Principles-Verdict: CONCERNS

The repo now carries two rg+python content-search engines: the new endpoint and the file-explorer app's, each with its own sensitive-exclusion fence.

Not justified as shipped

  • Item 3 — duplicate of src/kiro_crew/apps/builtins/file_explorer/server.py: grepped _search|grep there — an existing rg pass (_search_rg, line 749) and python fallback (_search_python, line 868) already answer "which files contain this text", carrying the same --iglob/negated-glob lore now spelled twice. The document pass, dashboard gating and stdin channel are meaningfully new, but the shared root cause — credential exclusions hand-projected into rg globs — is fixed here by deriving from sandbox_credential_targets() while its 1 counted sibling, the app's hand-kept glob list (server.py:777–811), stays unfixed and will diverge from is_sensitive_path. Accepted-and-deferred, since the app runs in its own process with its own allow-root model.
    Subtraction: replace the app's hand-kept exclusion globs with the same sandbox_credential_targets() derivation, deleting the second list.
    Clears when: the app's exclusions derive from the shared source, or a maintainer records the divergence as accepted.

What this change ships

Inventory (10 items) — 9 justified

Intent: let a user find which project files — Office documents included — contain a string, from the chat side panel's Files tab. ADDITION.

  1. Search file contents from the Files rail, one row per file, click opens at the line (verified: usePanelTabs.openFile consumes opts.line → revealLine → jumpToLine) — justified
  2. Word/PowerPoint/Excel text is searchable with location tags; PDF deliberately absent (pdfplumber has no memory ceiling) — justified
  3. New POST /api/file-grep endpoint, rg engine + python fallback, typed client — duplicate of src/kiro_crew/apps/builtins/file_explorer/server.py (text-engine half; see above)
  4. Name/Content toggle in words on its own row; Name stays the default — justified
  5. All/Changed segment hidden in Content mode, selection preserved on return — justified
  6. Status row names the count's unit, partial answers, and a skipped-documents floor — justified
  7. Slow-host tooltip states the consequence (no ripgrep, slower scan), not the engine name — justified
  8. Previous hits persist while refining a query, dropped on a project switch — justified
  9. Search mode remembered per page session, never persisted (content search costs a gateway walk) — justified
  10. Capture harness for real-browser evidence (7 frames × 2 themes; 501 sibling capture scripts counted) — justified

[FIRST-PRINCIPLES-REVIEWED] 843a178

@github-actions

github-actions Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

Opus 4.8 Review — ✅ no blocking findings

Reviewed 843a17806b7377b38e63809273632ee51f04c96d — this comment is updated in place on each push.

Review details

Content-search line numbering diverges between the ripgrep and python engines, breaking the module's own engine-parity contract.

FINDING — src/kiro_crew/dashboard/handlers/files.py:740 — raw.decode("utf-8", errors="replace").splitlines() splits on the full Unicode break set (\r, \f/\x0c, \v, \x1c–\x1e, \x85, \u2028/\u2029) while _grep_rg_hit_of reports ripgrep's \n-only line_number; a searched file carrying a form feed or bare \r (e.g. "page one\x0cneedle two\n") reports line=2 + preview "needle two" on a python host and line=1 + a preview containing the whole \x0c-joined region on an rg host — the same tree and query answer differently depending solely on whether the host has a vetted rg, contradicting the "two engines, one contract" invariant → Fix: in _grep_python, iterate raw.decode(...).split("\n") (stripping a trailing \r) so line numbering and preview extraction use ripgrep's \n-only line model, as the document pass already does with explicit \n rfind/find.

[OPUS-REVIEWED] 843a178

Verdict parsed from the review's SHA-scoped output markers for commit 843a17806b7377b38e63809273632ee51f04c96d.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 843a17806b7377b38e63809273632ee51f04c96d: <one-sentence reason>

@github-actions

github-actions Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review — ✅ no blocking findings

GPT 5.6 completed its review of 843a17806b7377b38e63809273632ee51f04c96d and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 843a178

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 843a17806b7377b38e63809273632ee51f04c96d: <one-sentence reason>

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Sep 14, 2026
@github-actions

github-actions Bot commented Sep 14, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Fable 5) — ✅ PASS

UX-level review of 843a17806b7377b38e63809273632ee51f04c96d — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

UX-Verdict: PASS

Flip Name↔Content live once — All/Changed vanishes unanimated and no recording shows it; confirm it reads as mode change, not breakage.

Suggestions

  • content_doc_note (en.manual.json) is three always-visible sentences repeated on every document-hit search in a 300px daily-use rail; compress to one, e.g. "A text hit opens at its line; a document opens from the start — the tag names the slide, or sheet and row (Word has none)."

[UX-REVIEWED] 843a178

@iamwhatever

Copy link
Copy Markdown
Contributor Author

mechanism: rg argv pinned to the fallback's semantics (--fixed-strings, --ignore-case, --no-ignore-vcs)

  • fixed: both engines now answer one tree identically, ignore file included span=6fbecb2b4fec

Fixed in 9b93695043. The Watch is right, and it was this round's largest defect:
the parity tests agreed only because no fixture tree ever carried an ignore file.
--no-ignore-vcs is in the argv, so NEITHER engine honours .gitignore. That is
the semantic the two can agree on exactly -- real gitignore semantics need
per-directory files and pathspec, and a root-only approximation in the fallback
would be a new divergence rather than a fix. _WALK_SKIP_DIRS still prunes the
noisy directories on both sides, which was never the half in disagreement.
Pinned as you asked: the fixture writes a .gitignore plus the file it covers.

Detail the ledger does not keep:

Two tests carry it — test_an_ignore_file_does_not_change_the_answer on both
engines, and test_both_engines_answer_one_tree_identically comparing them against
each other on that same tree.

Three sibling divergences on this span surfaced while fixing it and are fixed with
it: the query was a REGEX (a.c matched abc), --smart-case made a capitalised
query case-sensitive for text files while the document pass kept folding, and an rg
error exit under --no-messages was an empty stdout reported as an authoritative
zero matches.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: dropped col from _grep_hit and the byte->char derivation from _grep_rg

  • fixed by subtraction: col is out of the hit shape span=97b63dbe2cf8

Accepted and dropped in 9b93695043, including the byte->char derivation and its
tests. Symmetry with the Files app was the only defence and it is not one.

It removed a correctness surface too: ripgrep reports a BYTE offset while the
preview is decoded text, so the field needed a re-derivation over characters
to be right about any multi-byte line. Nothing read it. What remains is a test
that the preview comes back as the file's own characters, which is the part a
reader can actually see.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: removed _grep_include_globs, _grep_matches_globs, _GREP_MAX_INCLUDE_GLOBS and opts.include

  • fixed by subtraction: include= is gone end-to-end span=406928595e6b

Accepted and removed in 9b93695043. Zero consumers is the right bar and it was
unconsumed: no UI passed it, and the description defers glob inputs.

Removing it also retired a hazard rather than only surface. In ripgrep ANY
non-negated glob flips the whole glob set into allowlist mode, so a caller
glob silently excluded every file the set did not name. With include= gone
every glob in the argv is negated, and a test now asserts exactly that.

It returns with #7625's own include/exclude glob input PR, where a UI passes it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: yes
mechanism: deleted pdfPageOf + PDF_PAGE_LABEL from website/src/api/fileGrep.ts

  • fixed by subtraction: pdfPageOf and its regex are deleted span=33d7f8739293

Accepted and deleted in 9b93695043. You are right that its own comment claimed a
consumer it never had: it was written for a #page=N jump this PR then
decided not to build, and the export outlived the decision.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • needs-a-decision: consolidating this engine with the Files app's is a maintainer call span=8c3197335658

Not fixed, and asking rather than deferring: the duplication is real, but a PR
adding a dashboard endpoint should not be what decides it.
The two callers are not peers. The Files app is a separate stdlib-only process
whose safety rests on ALLOWED_ROOTS containment; this handler's rests on
_validate_dashboard_path + is_sensitive_path, plus _run_path_probe for pool
discipline the app has none of. A shared core must serve both gating models, and
getting that wrong means a search that reads a path one of the two would refuse.
Question: fold them and pick which containment the core enforces, or accept two
engines with one documented result shape? I can do either.

Detail the ledger does not keep:

What this PR did do is stop the copies drifting silently: the ignore, literal and
case divergences the Design lane found are now pinned by tests on this copy. The
macOS TCC exclusions the app carries are not needed here — the root is a project
directory the user named, never a bare $HOME.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

mechanism: hand-written red span replaced by ErrorNotice variant=inline askAgent

  • fixed: the failure state renders through ErrorNotice with the hand-off on span=6649dc29b8c9

Fixed in 9b93695043. errors-use-error-notice is blocking:true on src/**/*.tsx and
this was a new site, so there is nothing to argue.
It uses the form this same file already applies to a failed git status two rows
down: variant="inline", askAgent on -- a read failure has nothing unsaved to
lose -- and its own testId. A refused root or an exhausted probe pool is not
something the user can fix by retyping, which is the case the hand-off is for.

Detail the ledger does not keep:

The status line now keeps only the states that are not errors, and the test asserts
the notice carries role="alert" rather than matching the words alone — a
hand-written span would satisfy a bare text match, which is what let this ship.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: docs/feature-map/README.md row updated with the toggle, api/fileGrep.ts and /api/file-grep

  • fixed: the Files in chat row names content search and its endpoint span=d48021523229

Fixed in 9b93695043. Correct anchor, and worth noting the local
check_feature_map.py gate passed -- it checks the file's structure, not
whether a new handler is described, so nothing local would have caught this.

The row now names the Name/Content toggle, the document formats, the
api/fileGrep.ts client and GET /api/file-grep alongside the existing
endpoints.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

mechanism: preview redaction in _grep_hit; xlsx aggregate expansion ceiling; static engine for empty responses

  • fixed: all three findings in handlers/files.py span=0bf67dcbaf49

All three fixed in 9b93695043, none rebutted.
PREVIEWS (:4454) upheld correctly -- a secret in ordinary source is common and the
sensitive-path fence covers credential STORES, not that. Both redactors now run in
_grep_hit, the one row builder both passes call, and before the truncation.
XLSX (:4623): your reading of the shared vet is right, it bounds declared member
COUNT and central-directory size, not expansion. The path now also sums file_size
over infolist() against 200 MB, _SHEET_MAX_EXPANDED_BYTES's own figure.
PATH (:4809): the docstring asserted the invariant this broke. Empty responses now
report engine: "" -- honest, since no engine ran -- and the real probe stays inside
_search on the transfer pool.

Detail the ledger does not keep:

Previews — redaction sits at that chokepoint so a third pass cannot be added
without it. Before truncation because a secret straddling _GREP_PREVIEW_CHARS
would otherwise be halved first, and half a token matches no pattern. Three tests: a
credential on a matching line (both engines), one inside a .docx, and one pinning
the redact-then-truncate order against a shrunken cap.

XLSX — both gates are load-bearing rather than redundant: the inventory vet bounds
the ZipFile construction that the expansion check then needs. The ceiling runs before
the openpyxl import, not merely before the parse, so a refusal does not pay ~100ms of
parser setup for the thing it is refusing to run.

PATH — the more useful outcome is the guard, not the fix. The static ratchet in
test_dashboard_files_onloop_fs.py did not catch this, because shutil.which was not
in its _FS_NAMES. which is now in that list with the reason, and the can-it-fail
probe carries the shape — so the next handler with this bug fails the guard instead of
reaching review. No existing handler trips it.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

mechanism: rg argv gains --fixed-strings/--ignore-case; error exit and timeout split

  • fixed: ripgrep matches a literal, case-insensitively, like both other passes span=4de94a278762

Fixed in 9b93695043. Your chain is right in every part, including that a config(
parse error under --no-messages becomes an empty stdout and was reported with
truncated=False -- an authoritative "no matches" for a search that never ran.
--fixed-strings and --ignore-case are in, --smart-case is out. Two more on
the same line: returncode > 1 now takes the fallback (0 matches, 1 none, >1
error), and a TimeoutExpired no longer does -- the deadline is SHARED, so the
python pass would start with nothing left. It returns the hits rg already
printed, marked truncated.

Detail the ledger does not keep:

Four behavioural tests run per engine — the literal, the unbalanced query, the case
fold and the ignore file — plus argv assertions that run on a host with no ripgrep,
so the flags stay pinned where the behaviour cannot be exercised.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: status row title states the search hit its time limit and to narrow the query

  • fixed: the status line explains a partial answer and what to do span=4a09b29cd049

Fixed in 9b93695043. "capped" alone did read as a notice that might be clickable.

The row's tooltip now says the search stopped at its time limit, that the list
is therefore partial, and that narrowing the query gives a complete answer --
which is the actual recourse. A retry button would not be one: the budget is
wall-clock, so the same query would stop in the same place.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

mechanism: capture fixture previews rewritten; driver asserts one highlight per row

  • fixed: every fixture preview now contains the literal query span=251fb3cf2e84

Fixed in 9b93695043. The most useful finding in the set, because what was wrong was
the EVIDENCE, not the copy.
You are exactly right: the backend matches a literal, so
RATE_LIMIT_PER_MINUTE = 600 could never be a hit for "rate limit", and the rows
with no highlight are what made a code match and a document match look like
different things. All seven previews now contain the phrase verbatim.

Detail the ledger does not keep:

Two of my first replacements still carried rate_limit with an underscore — the same
defect again — so the driver now COUNTS highlights and fails unless every row has
one. That is the part that makes the fixture stay honest. All six frames re-captured
and re-attached.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: engine moved from the visible notes into the status row's title tooltip

  • fixed: the engine name is out of the status line span=0213c562dc76

Fixed in 9b93695043. The reader's misreading is the one that matters: "python"
taken as "narrowed to Python files" turns a diagnostic into a claim that the
result set is incomplete on purpose.

It is now in the row's tooltip, where it still answers "why was that slow"
without sitting in the result line. A test asserts the visible text does NOT
contain it and the title does.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

mechanism: document badge title names the location and states the viewer opens at the start

  • fixed the promise, not the jump: the badge says where the match is and where opening lands span=ab9187840d72

Fixed the broken promise in 9b93695043; deliberately not wiring the page.
You are right that a label the click ignores is friction. The badge's tooltip now
reads "Match at slide 7. Opening shows the document from the start." The row
still tells you where to look and no longer implies the click takes you there.
Wiring it is six hops -- onFileOpen, openFile opts, PanelTab, FileTabBody,
MarkdownPanel, ContentRenderer, PdfViewer, which today takes only filePath and
builds its own iframe src. revealLine exists for text and has no page twin.

Detail the ledger does not keep:

That is a panel-plumbing change across files this PR does not otherwise touch, and it
is item 3 of the "Not a goal" list in the intent comment. It belongs with #7625's
viewer work, alongside the grouped results and glob inputs.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: content_docs_skipped reworded to a label-then-number form in all twelve catalogs

  • fixed differently: the count follows a label instead of inflecting a noun span=3a83f9b91417

Fixed in 9b93695043, and you are right about the bug: at count=1 it read
"1 documents not searched".

I took the reword rather than the plural key. "documents not searched: {{count}}"
has no agreement to get wrong in ANY of the twelve languages, where _one/
_other fixes English and then needs correct case agreement across four
Russian forms that nothing in this loop can verify. Removing the class beat
adding twelve chances to get it wrong.

A test now pins count=1 reading correctly.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

self-added: no
mechanism: active toggle button renders a short text label beside its icon

  • fixed: the active mode names itself span=17178dde9ba8

Fixed in 9b93695043. Two bare icons were a guess, and the cost of guessing wrong
is silent -- the same query becomes a different search.

The ACTIVE button now carries its word ("Name" / "Text") and the inactive one
stays an icon, so only ever one label is showing and it fits the 300px rail.
That makes the pair a statement about what is happening now rather than a
legend to decode. Same icon+text shape the Changed segment already uses.

@iamwhatever
iamwhatever force-pushed the feat/sidepanel-content-search branch from d94e2b7 to 79d9e42 Compare September 14, 2026 14:01
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Sep 14, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Your clearing condition is "server.py:815 takes the same --file - channel, or a linked issue
records the deferral". I have done the second, and specifically rather than by pointing at an
issue that predates the finding: #10852 now carries a comment naming this exact gap —
#10852 (comment)

You are right that the harm as I described it is general. "A child's arguments are readable by
other accounts through /proc/<pid>/cmdline" is a fact about process arguments, not about this
handler, and apps/builtins/file_explorer/server.py puts a user-typed query on the command line
for the same reason mine did. Describing the harm in general terms while fixing one of two call
sites is fair to call a point patch.

What I have not done is fix it there, and the reason is the same one that governs the engine
consolidation this is a facet of: that app enforces ALLOWED_ROOTS in a separate process where
this handler enforces _validate_dashboard_path + is_sensitive_path inside the probe pool, so
touching its spawn means touching its trust boundary in a PR about the chat rail's file search.

The issue comment records both carry-overs concretely, so the follow-up does not have to
rediscover them: --file - for the pattern (with the line-break refusal that channel requires,
or the rg path starts matching what the python path cannot), and
validate_provider_executable for the binary, which the sibling also still lacks. Both are
single calls on that side.

I want to be plain that this leaves the sibling exposed. If the correct call is that a
general-harm finding must be fixed everywhere in the PR that names it, that is a defensible
position and it is the conductor's to take — but it is a scope decision, not something a further
rationale from me can settle.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Twelve frames re-captured at head bd9a14bda1, because this round changed visible copy: the
document note no longer promises a tag unconditionally ("…and when the format has a place inside
it to name, a tag after the file name shows where the text was found"), which is what shots 02 and
04 render. The driver's own assertions pass on every arm — badge shapes, one highlight per row,
mark counts 8 (results) / 4 (partial), and the note present in the results arm and absent in the
partial one.

Order: results, partial, hint, empty, error, Name mode — light then dark.

light-02-content-results

dark-02-content-results

light-03-content-capped

dark-03-content-capped

light-04-content-hint

dark-04-content-hint

light-05-content-empty

dark-05-content-empty

light-06-content-error

dark-06-content-error

light-01-name-mode

dark-01-name-mode

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • fixed: the sensitive globs are anchored under the search root span=f9ca2c4284fc

Fixed in bd9a14b, taking your suggested shape ("exclude only sensitive paths actually
rooted beneath root"). This record names head 2ee384b — the head your finding judged —
rather than the head that carries the fix; a record naming the fixing head claims a span that
no longer resolves, which is my error from the first posting of this disposition.

I verified the divergence rather than accepting it on the argument, because the whole claim
rests on what is_sensitive_path actually answers: /repo/proj/.npmrc → False, ~/.npmrc →
True. It is HOME-anchored, and there are 144 entries in that list, so this covered .npmrc,
.netrc, .pypirc, .git-credentials, .docker/config.json, .kube/config and the rest,
at any depth in any project.

So the two engines disagreed, and in the direction hardest to notice: the rg host silently
returned FEWER results than the python host for the same query, and a user would read that as
"the string isn't in my project". The per-hit filter is the declared authority and it never
asked for those files to be skipped; the glob was an optimisation that had quietly become
policy.

Each entry is now resolved to its absolute home path and emitted only when it genuinely lies
inside the tree being searched, as a root-anchored glob. Opus then caught that my first
version of this fix was still wrong for single-component leaves — !.ssh has no slash, and
under ripgrep's gitignore semantics a slash-less pattern matches a BASENAME at any depth, so
the "anchored" claim was false for exactly the entries that needed it most. It now emits
!/<relative>, and a test asserts over EVERY emitted pattern that it starts with !/ rather
than checking one entry, since a single-component leaf is the only shape that can lose its
anchor.

The property test is the one I would keep if I could keep only one: for a project root, no
--iglob exclusion in the argv may name a file that is_sensitive_path does not consider
sensitive under that same root. That fails if anyone re-broadens the glob, whichever entry
they do it with.

--iglob is kept: ripgrep still matches globs case-sensitively, so !/.aws would leave
.AWS searchable on a case-insensitive volume.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • fixed: the marker no longer resolves ripgrep at collection, so importing the suite creates nothing span=8e815689122b

Fixed in 0ebf334. This is a real side effect on the operator's machine and I introduced it
two rounds ago while fixing something else, so it is worth stating the chain rather than just
the patch.

requires_rg was a module-level pytest.mark.skipif(f._grep_rg_executable() is None, ...).
A skipif condition is evaluated at COLLECTION, and _grep_rg_executable resolves through
validate_provider_executable → agent_writable_roots() → workspace_root() →
_resolve_workspace_root, which ends in root.mkdir(parents=True, exist_ok=True). So merely
importing this test module created the workspace directory.

I verified the mechanism rather than reasoning about it, because it does not reproduce on my
host (no ripgrep here, so shutil.which returns None and the chain is never entered — which
is presumably why it took a CI reviewer to see it). Calling agent_writable_roots() directly
with a fresh KIROCREW_WORKSPACE pointing at a non-existent path creates that path. That is
the whole finding, confirmed.

The fix follows this repo's own convention: requires_git and requires_symlinks in
test/conftest.py are pure conditions, for exactly this reason. So the marker is
skipif(shutil.which("rg") is None) — a $PATH stat and nothing more — and a
_require_rg_engine() helper asks the provenance question from the test BODY, where a
directory-creating lookup is legitimate because a test is actually running.

Both halves are load-bearing, which is why I did not simply revert to the pure which check:
which and the resolver disagree wherever the chokepoint refuses a ripgrep that IS on $PATH
(an NFS home whose parents stat as the overflow uid 65534, a root gateway, a world-writable
parent), and with only the marker the rg arm of every parity pair would run the PYTHON engine
while reporting that it covered ripgrep — one engine asserted twice by a pair claiming two.

Verified after the change with a throwaway KIROCREW_WORKSPACE: collection exits 0, collects
101 tests, and the directory is not created. I checked that this probe can actually FAIL first
— my initial run reported PASS only because collection was erroring on a missing import, which
is the sort of green that means nothing.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • fixed: the placeholder keeps the previous answer only within the same project span=6649dc29b8c9

Fixed in 0ebf334. Legitimate, and the mechanism is exactly as you say: placeholderData: keepPreviousData keeps the last answer whenever the query KEY changes, and the key is
['file-grep', projectDir, settled] — so it kept the answer across a project switch as
readily as across a keystroke. Every row opens by absolute path, so those rows stayed
clickable and opened a file from the project the user had just left.

The placeholder is now a function that consults the previous query's own key and returns the
previous answer only when it names the same project, undefined otherwise. So refining a
query still narrows a visible list — which is the whole reason the placeholder is there, since
without it the list blanks under "Searching…" for the debounce plus up to the entire 2s
budget — and switching project blanks it, because a different project's answer is not an
approximation of this one.

The distinction I had missed is that those two key changes are not the same kind of event.
Narrowing a query makes the previous answer a superset of the next one, so showing it is
honest. Changing project makes it unrelated, and showing unrelated rows that are ACTIONABLE is
worse than showing none.

A vitest case covers it, and I checked that it discriminates rather than assuming: reverted to
keepPreviousData, the new test fails; with the fix, it passes. It re-renders on the same
QueryClient with a different projectDir while the next fetch is still in flight — the exact
window the placeholder used to fill — and requires the old project's row to be gone.
keepPreviousData is dropped from the import, so the old behaviour cannot be reinstated by
habit.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • fixed: the exclusion carries a leading slash, which is what actually anchors it span=4de94a278762

Fixed in 0ebf334. You caught a bug in the fix I made one round earlier, and the failure mode
is worse than the original because the docstring asserted the property the code had stopped
having.

The previous round replaced !**/<name> with !<relative> and called it root-relative. For a
multi-component entry like .config/gcloud that is true — a pattern containing a slash is
anchored under gitignore semantics. For a single-component leaf like .ssh it is false: a
slash-less pattern matches a BASENAME at any depth, so !.ssh hides every .ssh in the tree.
That is precisely the unanchored behaviour the change existed to remove, silently reintroduced
for the majority of the 144 entries, with a docstring claiming otherwise. Your parent-of-a-leaf
case is the sharpest form: searching a directory that CONTAINS a home directory would then hide
a project's .ssh several levels down.

It now emits "!/" + PurePath(inside).as_posix(). The leading slash is the anchor.

The test is written as the property rather than as your example, because a single instance
would not have caught this in the first place: it iterates EVERY emitted pattern and requires
each to start with !/. The neighbouring test additionally rejects both unanchored spellings
explicitly — !**/.aws and bare !.aws — so the two ways of losing the anchor are named
rather than implied.

Worth recording that this is the same shape of mistake three times over on this endpoint: a
rule applied to the case in front of me and not to the neighbouring case of identical kind
(the --iglob case-fold applied to sensitive dirs but not document extensions, the redaction
applied to preview then label then path, and now anchoring applied to multi-component paths but
not single-component ones). Writing the assertion over the whole set instead of over one entry
is the only thing that has reliably caught it, so that is what this one does.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Your clearing condition is "a linked issue records that consolidation (or the sibling gets the
same stdin-pattern + provenance treatment), or a maintainer records the deferral". The linked
issue is #10852, and it records both carry-overs by name rather than as a general wish:
#10852 (comment)

Concretely, what that comment now says the sibling needs, so the follow-up does not have to
rediscover it:

  1. --file - for the pattern, plus the line-break refusal that channel requires — --file is
    line-delimited, so without it a two-line query becomes two patterns OR-ed together and the
    rg path starts matching what the python path cannot.
  2. validate_provider_executable for the binary — the sibling still spawns a bare rg off
    $PATH.

Both are single calls on that side. Neither is done in this PR, which touches only
dashboard/handlers/files.py.

The reason it stays a follow-up is unchanged and is about a boundary rather than about tidiness:
apps/builtins/file_explorer/server.py enforces ALLOWED_ROOTS in a separate process where
this handler enforces _validate_dashboard_path + is_sensitive_path inside the probe pool.
Unifying the engines means reconciling those two authorization models, which is a change to that
app's trust boundary made from a PR about the chat rail's file search.

I am not going to pretend this leaves nothing open: the sibling's query is still on its command
line and its rg is still unvetted. If the right call is that a general-harm finding must be
fixed at every call site inside the PR that names it, that is defensible — but it is a scope
decision for the conductor, not something another rationale from me can settle.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • fixed: the status row names the unit — "one row per file" span=2665880b472c

Fixed in c73db04. The ambiguity is real and your reader's reading is the correct one to
worry about: every engine returns at most ONE row per file — --max-count 1 for ripgrep, a
break after the first matching line in the python walk, one segment per document — so "8
results" beside eight single-line rows leaves it open whether a result is a file or one spot
inside a file. Under the second reading the list looks like it is hiding the other matches in
each file, which is a worse impression than the truth.

I did not take your first option ("count 8 files") and I want to be straight about why, because
it is a real constraint and not a preference. The count renders
components.discoverySearchBar.result, which DiscoverySearchBar and the file-explorer
SearchPanel also use and which src/i18n/pluralKeys.json registers as a plural key.
Relabelling it means either changing the unit on two unrelated surfaces from inside a
file-search PR, or minting a new plural key and getting its categories right across eleven
plural systems — a risk I have already declined once on this PR for the same reason.

Nor did I take your second option verbatim (add it to content_doc_note). That note only
renders when a positionless hit exists, so a text-only result set — the common case — would
never see it, and the note is already three clauses long.

So the unit is named beside the count: the status row adds "one row per file", and only when
results.length > 0, because nothing found needs no description of the list. Two vitest cases
pin both halves, since a note that always rendered would be the next finding.

Translated across all twelve hand-maintained catalogs, en-XA regenerated (13846 keys), 19/19
i18n checks pass, and the twelve frames are re-captured at this head — the status line now
reads "8 results · one row per file" in shot 02 and "4 results · one row per file · partial · 6
or more documents not searched" in shot 03, while shot 05 (empty) correctly carries neither.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • push back on scope, unchanged: AskAgentButton is shared by 675 call sites span=87648efef8fc

Same answer as the last time this surface came up, and I am not going to dress it up as new
reasoning: the reader's hesitation is real and this PR is still not where it gets fixed.

The control is AskAgentButton inside components/ErrorNotice.tsx, reached by passing
askAgent. There are 675 <ErrorNotice> call sites across 201 files; this feature is two of
them, and the other is the pre-existing git_status_failed notice in the same rail. Its label
and tooltip come from the shared components.askAgent.* keys. Renaming it to answer "does this
cost anything, does it start work on its own" would change every error surface in the dashboard
from inside a file-search PR, and the reviewers of the other 673 would never see the change that
altered their copy.

On the substance: the control already answers the "what would it do" half through its tooltip —
open a chat with this error's context attached — and its behaviour is to open a chat with the
error attached, not to dispatch work. So the gap is that the answer sits in a tooltip rather
than in the label, which is a component-level copy decision with 675 stakeholders.

My offer stands and is concrete: I will open an issue against AskAgentButton carrying this
reader quote as the evidence, and link it here, if you want it filed. What I will not do is
change one call site's copy so this rail's button reads differently from the identical button
everywhere else, because that inconsistency is the next finding.

Worth noting what I DID change on the failure arm rather than leaving it untouched: the arm now
differs from the empty arm by icon (AlertTriangle vs a magnifier), by role="alert", by
colour and by carrying an action at all — the point of the earlier finding on the same shots —
so a reader who cannot interpret the button still knows this is a failure and not an empty
result.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • push back on the label, keep the hiding, and I agree a human should decide span=d733f5c77a71

You have separated this correctly and I agree with your own framing of it: "the incomprehension
is pre-existing icon-only design, but this diff makes it appear/disappear". So there are two
things and they get two answers.

The incomprehension — "no idea what either really does… I would not press the arrow one" — is
about a control this PR does not add, restyle, or change the rendering of. Labelling the
All/Changed segment would alter a control every user of this rail already has, on the strength
of a reader study commissioned against an unrelated feature, and it would land where nobody
reviewing the rail's own design would see it. That belongs in its own change with its own
reviewers.

The appear/disappear IS mine, and I am keeping it, with the reasoning now in the description
rather than only in the test list. The segment filters the tree by git status; searching the
staged-changes list is an explicit non-goal of this PR, so in Content mode the segment can only
mislead or do nothing. Disabling it instead was rejected because a disabled segment keeps its
active highlight and would still assert that a filter was in force. Hiding does not reset a
Changed selection — it survives and is honoured when the tree returns, with a test on exactly
that.

Where I think you are right and I was previously too quick: an unlabelled control that also
comes and goes is worse than an unlabelled control that merely sits there, so this diff does
make the pre-existing problem more visible even though it does not create it. That is a fair
charge and I am not disputing it.

And on your last clause — that a human should weigh this — I agree, which is why I am recording
the trade rather than declaring it closed. The options are: ship as is (the tree returns
unchanged, and the segment is exactly as comprehensible as it was before this PR), label the
segment here (fixes the reader's complaint, changes a shared control from the wrong PR), or stop
hiding it (puts a misleading filter back in Content mode). I have taken the first and the
conductor can overrule me on it. Frames 01 and 02 show both states so the behaviour is
reviewable as shipped rather than only described.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Twelve frames re-captured at head c73db0430d, because this round changed visible copy: the status row now names the unit ("8 results · one row per file"), and the empty arm correctly carries neither the count note nor the unit. The driver asserts every arm — badge shapes, one highlight per row, marks 8 (results) / 4 (partial), and the document note present in the results arm and absent in the partial one.

Order: results, partial, hint, empty, error, Name mode — light then dark.

light-02-content-results

dark-02-content-results

light-03-content-capped

dark-03-content-capped

light-04-content-hint

dark-04-content-hint

light-05-content-empty

dark-05-content-empty

light-06-content-error

dark-06-content-error

light-01-name-mode

dark-01-name-mode

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • fixed: file-search.md gains a /api/file-grep section covering the load-bearing decisions span=1224d73a8521

Fixed in e92aabb, and your clearing condition named the four things it had to cover, so this
is a checklist rather than a paraphrase.

You were right about the ownership question: docs/system-specs/modules/file-search.md already
lists handlers/files.py as its code surface and documents that module's search contract in
detail, so a second endpoint in the same handler belongs there. One line in the feature map
records that a feature EXISTS; it cannot carry a parity contract.

The new ### GET /api/file-grep section covers, in order:

  • the parity flags — each one named with the divergence it closes (--fixed-strings,
    --ignore-case over --smart-case, --no-ignore, --max-filesize, --max-count 1,
    --no-config), plus the --iglob-versus---glob asymmetry between document extensions
    (folded on both sides) and directory skips (folded on neither), and why every glob is negated;
  • the stdin pattern channel — /proc/<pid>/cmdline exposure, why the query is secret-class,
    --file -, and why a line break in the query is therefore refused;
  • the budget and partial semantics — one shared deadline, truncated, skipped_docs as a
    FLOOR, the threaded bounded-queue read, the oversize-record skip, and the dropped-sentinel
    completion;
  • the anchored-glob rule — that is_sensitive_path is HOME-anchored, that exclusions are
    emitted only for stores genuinely under the root, and that the leading slash is what anchors
    them under gitignore semantics.

Plus two things you did not ask for but which the section would be dishonest without: the
executable chokepoint (validate_provider_executable, and that a refusal degrades to the python
engine rather than failing), and the deadline-bounded document extraction with its
content-digest cache key and its refusal to cache a parse the deadline cut short.

The Overview now says the module owns two endpoints and what they do NOT share, "Scope of this
module" covers content as well as name, and the Key Files and Tests tables gained the new
handler role, the rail component, the client, and both test files. python3 scripts/docs_lint.py passes.

@iamwhatever

Copy link
Copy Markdown
Contributor Author
  • fixed: the body's embedded frames were eight rounds stale; they now point at the current captures span=1224d73a8521

You were reading real pixels and drawing the right conclusion from them. "The PR states 'Frames
re-captured at this head'; the pixels falsify that claim" — that was true, and it had been true
for a long time without my noticing.

What happened: the description embeds twelve user-attachments URLs, and those were the asset
ids from round 13. Every re-capture since — and there have been several, including the two
this round's copy changes required — went into a NEW evidence COMMENT, so the comment thread
had current frames while the body kept serving eight-round-old ones. The prose beside them was
updated each time. So the body was self-contradicting, and the lane that reads the body saw
the old status row ("8 results", no unit note) and the old unconditional document note, exactly
as you describe.

Fixed in e92aabb: all twelve embedded images now point at the captures taken at
c73db0430d, verified by asserting that none of the twelve round-13 asset ids survives
anywhere in the body. Those frames show 8 results · one row per file in the results arm,
4 results · one row per file · partial · 6 or more documents not searched in the partial arm,
the reworded note ("…when the format has a place inside it to name…"), and the tagless
docs/decision.docx row — so the rewording your blind reader's confusion prompted is now
cold-readable rather than merely claimed.

I also made the claim itself checkable instead of assertive: it now names the three strings a
reader should be able to see in the images, so a future stale-frame drift contradicts a
specific sentence rather than a general boast.

On your minor note — no frame covers the "Searching…" fetching state or the "Search in files…"
placeholder. That is accurate: the harness has four arms (ok/capped/empty/error) and both of
those are transient states of a live fetch. I have not added arms for them this round; if you
want them cold-read I will add a fetching arm that holds the promise open, and say so rather
than leaving it implied.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Feature-map panel fix (informational — the finding it answers no longer resolves at this head, so this is deliberately not a disposition record).

docs/feature-map/README.md:86 said "Chat left rail → files". Plainly wrong, and easy to check:
FileBrowserRail is mounted by pages/chat/SidePanel.tsx (and by FilesHomePanel.tsx), and the
feature map's OWN App-contributed-panel-tabs row calls that same SidePanel.tsx the "Chat right
panel". So the map contradicted itself two rows apart and mine was the wrong one — it also
contradicted the request this PR came from, which asked for content search in the chat side
panel's Files tab.

The row now reads "Chat right panel → Files tab, Name/Content toggle below the search field;
composer attach". The composer attach clause stays, because that part of the row describes the
pre-existing attach path, which really is reached from the composer.

Verified with the gate rather than by eye: FEATURE_MAP_BASE_REF=origin/main python3 scripts/check_feature_map.py reports that the map accounts for this change.

Fixed in e92aabb.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Twelve frames re-captured after this round's copy changes: the document note now leads with what the tag IS ("...the tag after its name says where the text was found — a page, a slide, a sheet and row. A Word file has no such place, so it shows no tag."), and the empty state reads "No results" rather than "No matches" so it no longer sits two words apart from the "0 results" count. Every driver assertion passes on every arm.

Order: results, partial, hint, empty, error, Name mode — light then dark.

light-02-content-results

dark-02-content-results

light-03-content-capped

dark-03-content-capped

light-04-content-hint

dark-04-content-hint

light-05-content-empty

dark-05-content-empty

light-06-content-error

dark-06-content-error

light-01-name-mode

dark-01-name-mode

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Twelve frames re-captured after PDF came out of the document pass. Visible changes: the results arm has one fewer row and one fewer tag (2 tagged document rows, 7 marked runs, "7 results"), the document note now says "a slide, or a sheet and row" with no page, and the hint no longer advertises PDF. Every driver assertion passes on every arm.

Order: results, partial, hint, empty, error, Name mode — light then dark.

light-02-content-results

dark-02-content-results

light-03-content-capped

dark-03-content-capped

light-04-content-hint

dark-04-content-hint

light-05-content-empty

dark-05-content-empty

light-06-content-error

dark-06-content-error

light-01-name-mode

dark-01-name-mode

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Stale-tree commit fixed (informational — the findings it answers should not resolve at the new head, so this is deliberately not a disposition record).

The design and first-principles lanes were right, and the diagnosis by blob identity was exact: 0d59a0be49 carried pre-d082722c1 copies of ~84 unrelated files and so reverted work landed by #11046, #10993, #10902, #10841, #10908, #10915, #10749 and others. git diff --name-only main...HEAD reported 112 files where this change touches 28.

How it happened

The squash sequence was git fetch origin main followed immediately by git add -A && git reset --soft origin/main && git commit.

The fetch advanced origin/main to a newer tip while the working tree was still based on the older one. reset --soft re-parents onto the new tip but keeps the index, so the commit's tree was the OLD tree under the NEW parent — which is exactly a revert of everything main gained in between.

The part that let it through review-side checks: the git rebase origin/main I ran afterwards reported "Current branch is up to date", because the commit's parent genuinely was origin/main. Only the tree was wrong. So the rebase could not fix it and gave a false all-clear.

How it was fixed

Rebuilt rather than patched, from a safety branch at the bad commit:

  1. git checkout origin/main -- . — every tracked file back to main's content, which restores the files the bad tree had deleted.
  2. git checkout 0d59a0be49 -- <the 28 file-search paths> — re-apply only this change.
  3. git reset --soft origin/main && git commit, then git rebase origin/main onto the newer tip that had landed in the meantime.

Verification (the invariant, not a spot check)

At the pushed head f08a1a3612:

  • git diff --name-only origin/main HEAD | wc -l → 28
  • that list diffed line-by-line against the intended file set → identical
  • git diff --name-status origin/main HEAD → 5 A, 23 M, zero D — no file main has is deleted or reverted
  • HEAD^ == origin/main tip
  • 131 pytest, 54 vitest, flake8/black/mypy, docs-lint, comment-history and i18n 19/19 all still green

The clearing conditions the lanes stated were "the diff no longer touches src/kiro_crew/pod/", "no .github/ workflow or script removed", "those paths drop out of the diff", and "all reverted files byte-identical to main". All four hold: the only paths in the diff are the 28 file-search surfaces the description enumerates.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

70863594d2 — three changes, one push (informational; the findings it answers were raised on c3261b72ff and should simply not recur at this head).

  1. Symlinked documents are no longer read (GPT F1 blocking, Opus advisory). _grep_docs now has the same os.path.islink(full) guard as _grep_python. Pinned by test_a_symlinked_document_is_not_reported: a .docx outside the root reached through an in-root link, with a plain .docx beside it as the control. Verified the test fails with the guard removed.

  2. The document extraction cache is gone. The LRU keyed by a content digest, _DocParse, its cacheable flag, the lock, _grep_cap_segments, and the nine tests that existed only to keep the cache honest — all removed. The shared 2 s budget already bounds what one keystroke can cost; the cache was 14 lines of code that drew findings in three consecutive rounds. _grep_doc_segments now returns (segments, whole), and whole=False (deadline, mid-read failure, character cap) still marks the answer partial.

  3. Comments cut to the load-bearing reason. Backend prose in the grep block went from 536 lines to 218; the col mention in the section header is corrected (GPT advisory). Code is unchanged apart from items 1 and 2.

Net: files.py +1182 → +780 lines; test_file_grep.py 1943 → 1774. Still 28 files, zero deletions against main, HEAD^ == origin/main. Local gates green: 126 pytest, 54 vitest, flake8/isort/mypy, docs-lint, feature-map, comment-history, i18n 19/19. No visible copy changed, so the twelve frames in the body still match.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

4834f6f9e5 — answers the two findings raised on 70863594d2.

GPT F1 (blocking), shared-string amplification in _grep_xlsx_segments. Fixed. The row is now assembled INSIDE the remaining character budget: each cell's text is appended only while it fits, the crossing cell is cut to what is left, and the loop stops there. No join over an uncapped list happens any more, so the largest string the row loop can build is _GREP_DOC_MAX_CHARS, however many cells reference one shared string. Pinned by test_a_wide_row_is_built_inside_the_budget_not_joined_then_cut (200 cells sharing one 88-char string under a 100-char cap: total text ≤ 100, whole=False, the in-budget match still found). Verified red with the budget check removed.

Opus advisory, NUL detection in _grep_python. Fixed. The python engine now treats a NUL anywhere in the read prefix as binary (b"\x00" in raw), not only in the first 16 bytes; ripgrep considers the whole file binary at its first NUL wherever it is. The tree fixture gains late.dat (4 KB of text, then a NUL, then the query on a later line), and the python-fallback shape test asserts it is not reported. Verified red with the 16-byte sniff restored.

Still 28 files, zero deletions, HEAD^ == origin/main (2b3f93126d). 127 pytest, lint/mypy, docs, feature-map, comment-history green locally. No visible copy changed.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

17ebda9983 — answers GPT F1 on d40dae3ca2 (query in the GET URL).

Fixed by changing the method, not by arguing. /api/file-grep is now POST with {"root", "q"} in the JSON body: the handler reads it through the module's read_bounded_json guard (same as /api/reveal and /api/file-write), the route is add_post, and fileGrep.ts calls apiTransport.post. The finding was right on my own terms — the handler already treats the query as secret-class (it is kept off the ripgrep argv and redacted before every SEL write), so a request target that proxies and access logs retain contradicted that.

Pinned by TestTheQueryTravelsInTheBody: a GET with ?q= is a 405; a body that is a list, a string or not JSON is a coded 400 rather than a 500; a null field is treated as absent. fileGrep.test.ts now asserts the URL does not contain the query and the body carries both keys. The newline guard's tests send the control character verbatim in the body (a JSON string carries it; a URL would have dropped it). Spec, feature map and description say POST.

The Coverage Gate red on d40dae3ca2 (src/api/fileGrep.ts 0/4) is answered by website/src/test/fileGrep.test.ts, which covers the file fully; the GPT run on 4834f6f9e5 before that ended with no [GPT-REVIEWED] marker after 62 minutes (no finding — the review did not complete).

29 files, zero deletions, HEAD^ == origin/main (69aeb28034). 132 pytest, 56 vitest, lint/mypy/eslint/tsc, docs, feature-map, comment-history, i18n 19/19 green locally. No visible copy changed.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Fourteen frames, re-captured at this head. New: the in-flight state the UX lane asked for — a seventh arm (?arm=searching) holds the /api/file-grep request open for the life of the page, so the frame is the rail mid-search: "Searching…" in the status row over the blank list region, light and dark. The driver asserts the word is up, no row or count has arrived, and nothing claims the search ran. Every other arm is unchanged in what it shows (2 tagged rows, 7 marked runs, "7 results" in the results arm). Every driver assertion passes on every arm.

Order: results, partial, hint, empty, error, searching, Name mode — light then dark.

light-02-content-results

dark-02-content-results

light-03-content-capped

dark-03-content-capped

light-04-content-hint

dark-04-content-hint

light-05-content-empty

dark-05-content-empty

light-06-content-error

dark-06-content-error

light-07-content-searching

dark-07-content-searching

light-01-name-mode

dark-01-name-mode

…uded

The chat side panel's Files tab could only search file NAMES. A Name/Content
toggle on its own row under the search field now asks the gateway which files
CONTAIN the text, and lists them as root-relative path, `:line`, and the matching
line with the match marked. Clicking a text hit opens the file at that line
through the reveal path the panel already has; a document hit opens the file at
its start, because a document has no line to reveal.

`POST /api/file-grep` with `{root, q}` in the body answers it -- a POST, because the query is secret-class text and a request URL is what proxies and access logs retain. A text pass runs `rg --json` where the
host has a ripgrep this endpoint may run, and an equivalent python walk where it
does not. The two are ONE contract, so ripgrep is pinned to the fallback's
semantics rather than its own defaults: `--fixed-strings` (both python passes
match `re.escape(query)`, so `config(` is a search and not a parse error),
`--ignore-case` rather than `--smart-case` (both fold case unconditionally),
`--no-ignore` (`os.walk` cannot honour ignore files), `--max-filesize` and
`--max-count 1` to match the fallback's own ceilings, and `--no-config` because
`RIPGREP_CONFIG_PATH` can carry `--pre=<binary>` and the child inherits this
process's environment.

The query is NOT in the argv. A child's arguments are readable by other accounts
through `/proc/<pid>/cmdline` and `ps`, and this handler already treats the query
as secret-class text -- it redacts it before every SEL write, because "which file
holds this key" is an ordinary reason to type a credential into a search box.
`--file -` hands the pattern over stdin instead, following the sandboxed-stdin
spawn in `cron_script.py`. That also retires the argument-terminator concern by
construction: a query starting with `-` cannot be read as a flag when it is not on
the command line. Because `--file` is line-delimited, a query containing a line
break is answered empty, joining the length bounds rather than earning a code of
its own -- both engines are line-oriented, so such a pattern matches nothing
either way, and saying so keeps the two channels equivalent.

Document containers are excluded with `--iglob`: the document pass claims a file
by `splitext(name)[1].lower()`, so a case-sensitive exclusion leaves `REPORT.DOCX`
in rg's pass and the file is reported twice. Directory skips stay case-sensitive,
matching the walk's own exact-name screen -- extensions are folded on both sides,
directory names on neither. Every glob is negated, which is load-bearing: one
non-negated glob flips ripgrep's whole set into allowlist mode.

The ripgrep it runs is resolved through
`github_runner.validate_provider_executable`, the repo's executable-provenance
chokepoint, rather than through a rule of this module's own -- the same function
`gh`, `glab`, `az`, `aws` and the terminal panel use, and the trust policy is
deliberately single-sourced there. It answers containment in the agent-writable
tree, ownership by a third account, world-writability through the whole parent
chain, symlinks, non-regular and non-executable files, a root gateway, the
Windows ACL where mode bits carry no information, and
`KIROCREW_PROVIDER_BIN_STRICT`. `require_protected` stays unset because `rg` is
handed no provider credentials, which keeps an ordinary Homebrew or
`~/.local/bin` install working; any refusal takes the python engine.

Both passes share one 2s budget and the answer says whether it was partial and
how many documents the budget did not reach, so "no matches" and "the search
stopped" stay different facts. ripgrep's records are read on a thread through a
bounded queue, because rg prints nothing for a non-matching file and an inline
read could not observe the deadline until rg chose to speak. A record over 64 KB
is skipped and marks the answer short rather than being truncated into invalid
JSON. A dead reader with an empty queue ends the search: the end-of-stream
sentinel is a non-blocking put, so a full queue drops it, and treating that as a
timeout would report a finished search as partial and hold the user for the rest
of the budget.

A document pass then extracts `.docx`/`.pptx`/`.xlsx` inside the same deadline,
re-parsing per request -- the 2 s budget already bounds what a keystroke can cost,
and an extraction cache had to carry the partial-parse flag with it to stay honest.
A parse that did not see all of a document's text marks the answer truncated.

`.pdf` is deliberately NOT in that set. Extracting PDF text has no memory ceiling
this process can enforce: pdfplumber exposes no length limit, the allocation is the
parsed character list itself, and the aggregate character cap is evaluated after a
page is appended -- so one page is unbounded, and a 25 MB input can decompress to
orders of magnitude more text. Without the extension a PDF is not a document to
this pass and both engines skip it as binary, which
`test_a_pdf_is_not_searched_at_all` pins with a `.docx` beside it so the assertion
cannot pass by finding nothing. Restoring it needs a resource-bounded extractor
shared with the identical exposure in `knowledge/readers.py:_read_pdf`, tracked in
#11052.

Every string a result row carries is redacted, asserted as a rule over the row
rather than field by field: preview, document label, and path. The path uses the
same `redact_path_segments` the tree and git listings in this module already use,
so a clean path stays byte-for-byte openable.

The All/Changed segment is hidden while Content mode is active and returns
untouched with the tree. It filters by git status, and searching the staged list
is out of scope; disabling it instead would keep its active highlight and still
assert a filter was in force. A hidden segment does not reset a Changed
selection.

The endpoint joins the off-loop ratchet -- root validation and the search both
run off the event loop, and the search takes a TRANSFER pool slot rather than a
probe slot because it holds its worker for the length of the search. `which` is
added to the ratchet's name list, repo-wide, because a `$PATH` walk is filesystem
work whose name does not look like it.

Related: #7625
@iamwhatever

Copy link
Copy Markdown
Contributor Author

843a17806b — answers the four items raised on 17ebda9983.

GPT F1 (blocking, upheld), the hand-off lost the journaled context. Fixed: FileBrowserRail now passes report={findReport(error.message)} to ErrorNotice, so the agent hand-off carries the endpoint, status and backend code the API layer journaled, not the human-readable line. Pinned by hands the agent the journaled report, not the generic sentence: a journaled 403 sensitive_path on /api/file-grep, a rejected search, a click on "Ask the agent", and the queued prompt must name all three. Verified red with the report prop removed.

UX BLOCK, no frame of the in-flight state. Fixed: a seventh capture arm, ?arm=searching, holds the /api/file-grep request open for the life of the page; the driver waits for "Searching…", asserts no row, no count and no "No results" arrived, and the frame is the rail mid-search. Fourteen frames re-captured at this head (comment above); the description embeds all fourteen and its claims sentence names the new arm's visible word.

Opus advisory, _grep_rg discarded hits on an error exit. Fixed: an exit > 1 AFTER hits were printed returns them marked truncated; only an error exit with nothing printed takes the python fallback (which would start on the same spent deadline). Pinned by test_an_error_exit_after_hits_keeps_them_as_a_partial_answer.

Windows shard 4, test_every_call_site_records_a_cap_decision. The new read_bounded_json call site needed a row in _CAP_REGISTER: api_file_grep is <default> / bounded control fields — a root path and a query the handler caps at 200 characters.

30 files, zero deletions, HEAD^ == origin/main (69aeb28034). 183 pytest (three files), 57 vitest, lint/mypy/eslint/tsc, docs, feature-map, comment-history, i18n 19/19 green locally.

UX Watch items (the "Ask the agent" hesitation in the shared ErrorNotice; the icons-only All/Changed segment) are pre-existing shared surfaces this PR does not own; the second is exactly the follow-up the description already names.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

The lane's own text says accepted-and-deferred; #10852 is that record, and it now names this subtraction explicitly (derive server.py's globs from sandbox_credential_targets(), delete the hand-kept list).
#10852 carries deferred-finding, an assignee, and Due: 2026-10-15.
Not folded here: the app enforces ALLOWED_ROOTS in its own process and this PR's pinned intent names sharing that model as a non-goal; the refactor is of code this PR does not own.
This PR's side is already derived, not hand-kept — the divergence risk the item names lives only on the sibling.

@iamwhatever

Copy link
Copy Markdown
Contributor Author

Real, and advisory: it moves a hit's line and preview only for a text file carrying \f, \v, \x1c–\x1e, \x85, \u2028/\u2029 or a bare \r; \r\n files answer identically on both engines.
Fix is a one-liner (split("\n") + trailing-\r strip) and belongs with the engine-parity contract #10852 consolidates, where the same line model has to be pinned for the sibling's _search_python too.
Not pushed at this head: every push re-runs all five lanes, and the PR is otherwise green.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants