feat(sessions): return the passages around a hit on request

[bompus]

codegraph_sessions and codegraph sessions gain context / --context <n> (0 to 5, implies full). Each hit comes back with the n passages before and after it from the same transcript, in transcript order.

How it works. A transcript's passages are inserted in one transaction, so its rows are consecutive and in order. The neighbours are the adjacent rows with the same file. No schema change and no second lookup call.

Budget. Neighbours draw on the existing 16,000-byte full budget after every hit's own passage, nearest first, rank by rank. Context never costs a hit its passage. When neighbours are cut, the answer says how many.

Secrets. Passages are returned as stored, credentials included. This matches the default snippets and the transcript files on disk, so there is no redaction (decided with the maintainer). The README, site docs, CHANGELOG and server instructions say so.

Checks.

• tsc --noEmit clean; sessions-index, cli-sessions-command, readme-sync, mcp-tool-allowlist, worktree-detection pass locally (62 + 42 tests); check:agent-docs 13318/32768 bytes.
• New tests cover order and sides, transcript ends and no cross-transcript leakage, the clamp to 5, order after a re-index, and budget order with the cut count.
• Full CI runs on the PR.

README rows checked. The CLI line, the codegraph_sessions tool row and the site CLI and MCP pages are updated. No count or benchmark row moves, and no other "About this fork" row is affected.

Summary by CodeRabbit

• New Features
  • Added a --context <n> option to session searches, including the CLI and MCP tool. Choose up to five neighboring passages on each side of a matching passage; requesting context also enables full-passage output.
  • Neighboring passages share the existing response-size limit with matching passages. Results report when some context passages are omitted.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: Repository YAML (base), Organization UI (inherited)
• Review profile: CHILL
• Plan: Advanced
• Run ID: 05c214d8-1da0-4c1b-aae9-ede4f845c4f6

---

📥 Commits

Reviewing files that changed from the base of the PR and between 6a90014 and 10460fc.

---

📒 Files selected for processing (10)

• CHANGELOG.md
• README.md
• __tests__/cli-sessions-command.test.ts
• __tests__/sessions-index.test.ts
• site/src/content/docs/reference/cli.md
• site/src/content/docs/reference/mcp-server.md
• src/bin/codegraph.ts
• src/mcp/server-instructions.ts
• src/mcp/tools.ts
• src/sessions/index.ts

---

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

---

📝 Walkthrough

Walkthrough

Session search accepts a context count from 0 to 5. Full results can include neighboring passages from the same transcript, subject to a shared 16,000-byte budget. The CLI and MCP documentation and tests describe and validate the option.

Changes

Session Search Context

Layer / File(s)	Summary
Context option and entry points src/sessions/index.ts, src/bin/codegraph.ts, src/mcp/tools.ts, src/mcp/server-instructions.ts, README.md, site/src/content/docs/reference/*, CHANGELOG.md	Session search, the CLI, and the MCP tool accept a context count. A positive count implies full results. Documentation describes the option and its range.
Neighbor selection and passage budget src/sessions/index.ts	Full search results can include nearby passages from the same transcript. The shared byte budget prioritizes hit passages, then nearer neighbors, and reports omitted neighbors.
Context output and validation src/sessions/index.ts, __tests__/sessions-index.test.ts, __tests__/cli-sessions-command.test.ts	The formatter labels and quotes neighboring passages and reports omitted context. Tests cover passage order, transcript boundaries, clamping, re-indexing, budget behavior, and CLI output.

---

Priority: ⬇️ Low

Merge Risk | ⚪ Minimal · up to 10460

Merge Risk: ⚪ Minimal · up to 10460

Session searches can return bounded neighboring passages without an established merge-blocking issue. Merge after the normal checks complete.

Security Architecture Review

Security architecture risk: 🔵 Low · up to 10460

Context requests can return credentials from passages that did not match the search. The option is explicitly requested, remains confined to the selected transcript, and shares the existing text budget. No broader project access or privilege increase was identified.

Retained concerns

• Low · security · inferred: An explicitly requested context window can disclose credentials in adjacent passages unrelated to the search terms. Raw matching-passage access already existed, but this PR adds nonmatching text to the same output channel without redaction. Same-transcript confinement, the shared text budget, and documented behavior limit the concern; they do not prevent incidental secret disclosure.

Security review details

Security Blast Radius

• observed — A context lookup is confined to the hit's transcript in the selected project index. The existing projectPath mechanism can select other initialized projects accessible to the server process; this capability is not newly introduced. Path validation and index-root selection are not evidence of caller-specific tenant authorization.

Security Findings and Attack Paths

• inferred — A caller able to invoke session search can request context around a benign matching passage and receive adjacent credential-bearing text without searching for that credential. MCP returns it as tool-result text, while CLI can emit text or JSON. No actual credential or downstream use was verified; any downstream reach would depend on the returned credential's privileges, which are unknown.

Trust Boundaries and Controls

• observed — Caller-controlled context is bounded before retrieval. Existing tool-allowlist enforcement, project-path checks, selected-root resolution, session opt-out, same-file SQL filtering, and shared text-budget enforcement remain applicable. Transcript prose is returned as data; this path does not execute it or automatically use credentials found in it.

Resilience and Maintainability Implications

• observed — Added tests exercise same-transcript confinement, transcript ends, context clamping, sequential reindex ordering, and text-budget behavior. These tests support normal-path containment but do not establish concurrent read-snapshot consistency or production caller authorization.

Hardening Proposals

• proposed — Where agents are less trusted than stored transcript data, consider an operator-controlled secret-handling policy for session output rather than relying only on caller-selected context and credential warnings. This is deployment-dependent hardening, not a verified authorization bypass.

---

Pre-merge checks | 6

✅ Passed checks (6 passed)

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely describes the main change: adding optional surrounding passages to session search results.
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.
Suppressions Explained		The pull request adds no lint, type-check, compiler, or warning-suppression directive. The changed files contain session implementation, CLI/MCP code, tests, and documentation only. Added lines contai…
User-Visible Changes Documented		The pull request adds the --context <n> CLI flag and the context MCP argument. README.md documents both changes, and the matching site pages site/src/content/docs/reference/cli.md and `site/sr…

---

✨ Finishing Touches 💡 1

📝 Generate docstrings

• Commit to this branch
• Create a new PR

---

---

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

🛠️ Fix failing CI checks 💡

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

_{Comment @coderabbitai help to get the list of available commands.}