sessions: field-scoped search terms (title:, branch:, msg:, has:pr) — you cannot aim the query at one field

[grimmerk]

Symptom

Searching pr-2 in the Sessions tab returns five sessions. The user wanted the one whose title mentions it, and could not tell which one that was — every row showed a highlight somewhere, but the highlights were in different fields.

pr-2                                                    5 sessions
  codev * codev 0820 refine …           match #37  "開 [PR-2] feat-sessions-…
  fred  * fred -> fred-service …        match #251 "[PR-2](shared-workflows…
  fred-custom-defer * agentic-fred …    match #12  …你一直提到 "cts" 是指? 3. "[PR-2]:…
  fred-custom-defer * agentic-fred …    …的 session, 來開始做 [pr-2] 3. …
  public-api-ff * public-api-ff & …     match #111 …infra doc update [pr-2] 0712

All five matched in user prompts. None matched in a title — but nothing in the row says so, so the only way to find out is to scan four lines of each row hunting for the amber background.

(The row the user was after has the title agentic-fred harden again - pr2-1533-v7-readiness — …, which contains pr2, not pr-2. Verified against the transcript. Searching pr2 does highlight it. That confusion is itself part of the motivation: without a way to scope the query, a near-miss is indistinguishable from a hit in another field.)

The gap

Search covers every session × every user prompt (PR #132) plus the enrichment fields — title, branch, PR link, last AI reply. That breadth is what makes it useful, and it is also what makes a query like pr-2 return five rows when the user meant one field.

There is currently no way to say which field to search.

Proposal: field-scoped query terms

title:pr2        only custom titles
branch:mcp       only branch names
msg:pr-2         only user prompts
project:fred     only project name / path
has:pr           only rows carrying a PR badge
after:2026-08-01 only sessions active since

Bare words keep today's meaning (search everything), so nothing existing changes.

Notes on implementation:

• This is B4 in docs/session-finding-plan.md §6, already planned. This issue records the concrete motivation and a measured instance.
• The parser belongs in session-search.ts as a pure module, and it is the same parser the PR-reference canonicalization needs (#123 ⇄ https://github.com/o/r/pull/123, plan §4.6) — 80.6% of PR mentions are reachable by only one of the two forms today. Doing them together is materially cheaper than doing either alone, and has:pr / pr:1598 fall out of the same work.
• Both search paths must use the parser, not just one: the main-side full-prompt search (claude-session-utility.ts) and the renderer's filterSessionsLocally. One rule, two implementations is how this codebase has produced bugs repeatedly — see PR feat(sessions): pin browse modes — recency order, ungroup, pinned-only #137's read-authority saga.
• title: and branch: are renderer-side only (enrichment lives there), msg: is main-side only. The union already handles that split; the parser just has to route.

Not in scope here

Telling the user which field a row matched on — that is the other half of the same complaint, tracked separately so each can ship on its own.

Priority

Medium. The search works; this is about aiming it. Worth doing with the PR-reference parser rather than as a standalone piece.

🤖 On behalf of @grimmerk — generated with Claude Code

[grimmerk]

Companion issue for the other half of this complaint: #141 — telling you which field a result matched on, for when you did not scope the query. #140 aims the search; #141 explains the result.

🤖 On behalf of @grimmerk — generated with Claude Code