@cassiomc1/forgeloop 1.10.2 → 1.11.1

package/.cursor/rules/project-loop.mdc

@@ -10,6 +10,7 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 1. Read [`LOOP_ENGINEERING.md`](../../LOOP_ENGINEERING.md) and [`PROTOCOL_INTEGRATION.md`](../../PROTOCOL_INTEGRATION.md).
 2. Confirm [`PROJECT_PROFILE.md`](../../PROJECT_PROFILE.md) from real sources; initialize if in `template` mode.
 3. Use [`GUIDE_ROUTER.md`](../../GUIDE_ROUTER.md) to activate relevant guides and report IDs.
+3. For repository-wide textual discovery, prefer `forgeloop search` and treat its results as discovery only; do not use them as verification evidence or scope authority.
 4. Respect higher-level and local instructions and the latest request.
 5. Make the minimum change, run specific checks, and run proportional regression checks.
 6. Diagnose failures before fixing them; do not repeat attempts without new evidence.
@@ -41,5 +42,4 @@ before asking. Do not ask the user to choose among reversible local
 product-positioning alternatives; the canonical checklist and boundary remain
 in `LOOP_ENGINEERING.md`.
 
-External workflow approval rules do not override ForgeLoop's autonomous-mode
-precedence; consult `LOOP_ENGINEERING.md#external-workflow-compatibility`.
+External workflow approval rules do not override ForgeLoop's autonomous-mode precedence; consult `LOOP_ENGINEERING.md#external-workflow-compatibility`.

package/.forgeloop/forgeloop.gitignore

@@ -1,3 +1,4 @@
 # Local resumable task state is untrusted, target-specific data.
 work-state.json
 executions/
+repository-index/

package/.github/copilot-instructions.md

@@ -11,6 +11,7 @@ Use these instructions across the repository while preserving local rules.
 - If an official ForgeLoop structured integration is available in your host, prefer it for protocol operations; otherwise use the project-local ForgeLoop CLI. Never simulate ForgeLoop-managed lifecycle, claim, recovery, ledger, or completion state directly.
 - Confirm [`PROJECT_PROFILE.md`](../PROJECT_PROFILE.md) from evidence; initialize if in `template` mode.
 - Select context with [`GUIDE_ROUTER.md`](../GUIDE_ROUTER.md) and report activated guide IDs.
+- For repository-wide textual discovery, prefer `forgeloop search` and treat its results as discovery only; do not use them as verification evidence or scope authority.
 - Respect the latest request, scope, and higher-level instructions.
 - Make the smallest coherent change; validate with specific and regression checks.
 - Diagnose causes before fixing failures; do not make unverified attempts.
@@ -41,5 +42,4 @@ before asking. Do not ask the user to choose among reversible local
 product-positioning alternatives; the canonical checklist and boundary remain
 in `LOOP_ENGINEERING.md`.
 
-External workflow approval rules do not override ForgeLoop's autonomous-mode
-precedence; consult `LOOP_ENGINEERING.md#external-workflow-compatibility`.
+External workflow approval rules do not override ForgeLoop's autonomous-mode precedence; consult `LOOP_ENGINEERING.md#external-workflow-compatibility`.

package/AGENTS.md

@@ -10,6 +10,7 @@ Do not treat ForgeLoop as vendor-specific, optional, or to follow only "in spiri
 1. If an official ForgeLoop structured integration is available in your host, prefer it for protocol operations; otherwise use the project-local ForgeLoop CLI. Never simulate ForgeLoop-managed lifecycle, claim, recovery, ledger, or completion state directly.
 1. Inspect [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md). Confirm facts from sources; initialize if in `template` mode.
 1. Use [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md) to select relevant guides and report activated guide IDs.
+1. For repository-wide textual discovery, prefer `forgeloop search` and treat its results as discovery only; do not use them as verification evidence or scope authority.
 1. Make the smallest coherent change, run specific checks, and proportional regression checks.
 1. Diagnose failures before fixing; do not repeat attempts without new evidence.
 1. Do not install software, publish, delete, or migrate data without authority. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.

package/AGENT_COMPATIBILITY.md

@@ -24,3 +24,10 @@ retained as a deprecated compatibility stub:
   immutable handoff.
 - Preserve the distinction between `consumerId`, harness labels, and
   authenticated identity; none grants authority or transfers claims.
+- For repository-wide textual discovery, prefer `forgeloop search` and its
+  provider-neutral contract. Do not require a host-installed `grep`, `rg`, or
+  `tgrep`, and do not silently substitute one when the mandatory index is
+  unhealthy.
+- Treat Repository Index results as local discovery context only. They are not
+  evidence, completion truth, task ownership, or authority to execute a
+  command.

package/CLAUDE.md

@@ -12,6 +12,7 @@ When working in this repository:
 1. If an official ForgeLoop structured integration is available in your host, prefer it for protocol operations; otherwise use the project-local ForgeLoop CLI. Never simulate ForgeLoop-managed lifecycle, claim, recovery, ledger, or completion state directly.
 1. Verify [`PROJECT_PROFILE.md`](./PROJECT_PROFILE.md) against real sources; initialize if in `template` mode.
 1. Consult [`GUIDE_ROUTER.md`](./GUIDE_ROUTER.md), select relevant guides, and announce their IDs.
+1. For repository-wide textual discovery, prefer `forgeloop search` and treat its results as discovery only; do not use them as verification evidence or scope authority.
 1. Make small changes, run specific checks, and run proportional regression checks.
 1. Investigate root causes before fixing failures; do not make unverified attempts.
 1. Request authority for unrelated installations, publications, deletions, or migrations. Do not install a missing verification tool merely to satisfy a check. For missing Qwen-MM-Plugins, follow `LOOP_ENGINEERING.md`.

package/DOCS_INDEX.md

@@ -18,6 +18,8 @@ integration and guide context. Use this map before editing documentation.
 | Cross-harness continuity | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) | Operational resume guidance, immutable handoffs, and multi-tool resumption |
 | Agent bootstrap summary | [`docs/AGENT_PROTOCOL_SUMMARY.md`](./docs/AGENT_PROTOCOL_SUMMARY.md) | Generated concise navigation aid for protocol invariants and commands |
 | CLI command reference | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) | Full syntax, options, and JSON examples for all commands |
+| Repository Index and Search | [`docs/REPOSITORY_INDEX.md`](./docs/REPOSITORY_INDEX.md) | Mandatory managed engine, indexed search contract, lifecycle, resource, security, and benchmark behavior |
+| Persistent CLI search transport | [`docs/PERSISTENT_SEARCH_TRANSPORT.md`](./docs/PERSISTENT_SEARCH_TRANSPORT.md) | CLI-only local IPC, host lifecycle, ownership, recovery, bounds, privacy, and direct API/MCP boundary |
 | Artifact and schema reference | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) | Purpose, mutability, and trust classifications of `.forgeloop/` |
 | Durable actions and trajectory evidence | [`docs/EXECUTION_TRACE.md`](./docs/EXECUTION_TRACE.md) and [`docs/RECIPES.md`](./docs/RECIPES.md) | Action provenance, reconciliation, metrics, and project-local evaluation |
 | Troubleshooting and recovery | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) | Symptom-first recovery and stable error code reference |
@@ -77,6 +79,7 @@ is historical evidence and is not part of the published core package.
 | **External runtime / orchestrator integrator** | [`ORCHESTRATOR_INTEGRATION.md`](./ORCHESTRATOR_INTEGRATION.md) |
 | **Resuming another tool / session** | [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md) |
 | **Looking up CLI commands** | [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md) |
+| **Understanding persistent CLI search transport** | [`docs/PERSISTENT_SEARCH_TRANSPORT.md`](./docs/PERSISTENT_SEARCH_TRANSPORT.md) |
 | **Inspecting `.forgeloop/` files** | [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md) |
 | **Fixing a broken or stale state** | [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md) |
 | **Looking for quick recipes** | [`docs/RECIPES.md`](./docs/RECIPES.md) |
@@ -99,6 +102,8 @@ is historical evidence and is not part of the published core package.
 - **Inspect real execution PoC and audit evidence**: [`poc/README.md`](./poc/README.md)
 - **Resume after switching tools**: [`docs/CROSS_HARNESS_CONTINUITY.md`](./docs/CROSS_HARNESS_CONTINUITY.md)
 - **Check CLI options and syntax**: [`docs/CLI_REFERENCE.md`](./docs/CLI_REFERENCE.md)
+- **Search the repository through ForgeLoop**: [`docs/REPOSITORY_INDEX.md`](./docs/REPOSITORY_INDEX.md)
+- **Understand persistent CLI search transport**: [`docs/PERSISTENT_SEARCH_TRANSPORT.md`](./docs/PERSISTENT_SEARCH_TRANSPORT.md)
 - **Understand what `.forgeloop/` stores**: [`docs/ARTIFACT_REFERENCE.md`](./docs/ARTIFACT_REFERENCE.md)
 - **Fix a blocked, stale, or invalid state**: [`docs/TROUBLESHOOTING.md`](./docs/TROUBLESHOOTING.md)
 - **Recover a stale task or reacquire released claims**: [`docs/RECIPES.md`](./docs/RECIPES.md#recipe-15--release-and-reacquire-claims-for-an-abandoned-task)
@@ -130,6 +135,11 @@ process into adapters or README sections; link to the canonical source.
 7. Use [`docs/REVISION_PROVIDERS.md`](./docs/REVISION_PROVIDERS.md) and
    [`docs/CODE_ATTESTATION.md`](./docs/CODE_ATTESTATION.md) when verification
    scope, provider boundaries, signing, or revision-range coverage is involved.
+8. Use [`docs/REPOSITORY_INDEX.md`](./docs/REPOSITORY_INDEX.md) for repository
+   discovery and [`docs/PERSISTENT_SEARCH_TRANSPORT.md`](./docs/PERSISTENT_SEARCH_TRANSPORT.md)
+   for the CLI-only local transport; search output remains operational context
+   and never replaces guides, contracts, verification evidence, or completion
+   validation.
 
 ## Verification and release
 

package/LOOP_SYSTEM_DESIGN.md

@@ -173,6 +173,18 @@ API-backed operations remain disabled until their documented credentials or
 service endpoints are configured. The kit links to the upstream project but
 does not bundle its source, MCP server, model, or dependencies.
 
+### Repository Index
+
+The Repository Index is a mandatory, provider-neutral discovery boundary for
+Git repositories. The CLI, Integration API, and MCP adapter share one search
+service backed initially by a ForgeLoop-managed, pinned Microsoft `tgrep`
+1.0.3 executable. The executable is verified before use; the project index
+under `.forgeloop/repository-index/tgrep/` and `engine-state.json` are derived
+cache/state outside the task ledger. Index health can block operational
+readiness, but index contents never become evidence, completion authority,
+task ownership, or historical truth. A host uses `forgeloop search` rather
+than assuming `grep`, `rg`, or `tgrep` is present on PATH.
+
 ### `GUIDE_ROUTER.md`
 
 Canonical map between request or project signals and applicable guides. Each route records:

package/ORCHESTRATOR_INTEGRATION.md

@@ -34,6 +34,15 @@ Any non-terminal state → BLOCKED when a genuine blocker is evidenced
 - `COMPLETE`
 - `BLOCKED`
 
+## Repository Index readiness
+
+For Git repositories, the mandatory Repository Index is an operational
+readiness dependency, not a second workflow state machine. An orchestrator
+should surface `index-status` health and route repair through the canonical
+`index-setup`, `index-start`, `index-stop`, and `index-rebuild` commands. An
+index failure must not rewrite historical completion, task claims, receipts,
+or verification evidence; discovery remains non-authoritative cache/state.
+
 ## Canonical transition table
 
 | From | Condition | To |

package/PROTOCOL_INTEGRATION.md

@@ -191,6 +191,23 @@ from Protocol v1, schema v1, and Integration API v1:
 | `canonicalHandoffs` | v2 | Immutable handoff snapshots with ledger-backed exactly-once operational acceptance |
 | `advisoryContextProviders` | v1 | Lazy, opt-in, provider-neutral Integration API injection only |
 
+`repositoryIndex` v1 is a mandatory provider-neutral discovery capability for
+Git repositories. ForgeLoop currently implements it with a managed, pinned
+Microsoft `tgrep` 1.0.3 release. `protocol-info --json` and the stable
+Integration API advertise the same `repository/search` operation and
+`repository/index-status` project resource used by the CLI and MCP adapter.
+The index is derived local cache/state: it is never lifecycle evidence,
+completion authority, task ownership, or historical source of truth. Hosts
+must not replace an unhealthy index with a silent `rg`, `grep`, or PATH-based
+fallback, and must not treat search results as proof of verification.
+Normal structured search and status projections are path-safe: match paths are
+repository-relative and machine-local repository, index, state, and binary
+paths are omitted across the CLI, Integration API, and MCP adapter. The first
+query performs strong readiness validation; warm queries use a per-repository
+process-local readiness cache with one bounded recovery retry after a
+server/index failure. Native exit code `1` remains a successful zero-match
+result.
+
 `canonicalHandoffs` v2 advertises `supported: true`, immutable snapshots,
 `lifecycleAuthority: false`, `evidenceAuthority: false`,
 `exactlyOnceAcceptance: true`, `acceptanceLedgerBacked: true`, and the

package/README.md

@@ -13,10 +13,10 @@
 [![Release notes](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml/badge.svg?branch=main)](https://github.com/cassiomc1/forgeloop/actions/workflows/release-notes.yml)
 
 ForgeLoop is a portable, vendor-neutral protocol for AI-assisted development
-and developer workflows. It turns an outcome into a contract, deterministic
-routing, resumable state, evidence-backed verification, recovery, cross-harness
-continuity, and validator-backed completion. It is a protocol/support CLI, not
-an agent or LLM runtime, not an agent framework, and not a graph orchestrator.
+and developer workflows. It turns outcomes into contracts, deterministic routing,
+resumable state, evidence-backed verification, recovery, cross-harness
+continuity, managed repository-wide discovery, and validator-backed completion.
+It is a protocol CLI, not an agent or LLM runtime, framework, or graph orchestrator.
 
 The operational sources are indexed in [`DOCS_INDEX.md`](./DOCS_INDEX.md).
 [`LOOP_ENGINEERING.md`](./LOOP_ENGINEERING.md) is the canonical process;
@@ -94,6 +94,7 @@ Then, inside your project repository:
 ```bash
 forgeloop init
 forgeloop doctor
+forgeloop search "example"
 ```
 
 If you prefer not to install globally, use `npx`:
@@ -427,7 +428,7 @@ The canonical source is the typed Archify workflow
 [`docs/diagrams/forgeloop-engineering-flow.workflow.json`](./docs/diagrams/forgeloop-engineering-flow.workflow.json).
 The committed animated interactive explorer is
 [`docs/assets/diagrams/forgeloop-engineering-flow.html`](./docs/assets/diagrams/forgeloop-engineering-flow.html),
-which opens in the dark presentation stage and traces the workflow. The
+which traces it. The
 animated, self-contained SVG fallback is
 [`docs/assets/diagrams/forgeloop-engineering-flow.svg`](./docs/assets/diagrams/forgeloop-engineering-flow.svg),
 and the deterministic hash receipt is
@@ -435,20 +436,21 @@ and the deterministic hash receipt is
 The governance source is [`docs/diagrams/manifest.json`](./docs/diagrams/manifest.json),
 and the source-bound visual approval is kept in
 [`docs/diagrams/reviews/forgeloop-engineering-flow.review.json`](./docs/diagrams/reviews/forgeloop-engineering-flow.review.json).
-The broader architecture and boundaries are in
-[`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md).
+The broader architecture and the CLI-only search boundary are in
+[`LOOP_SYSTEM_DESIGN.md`](./LOOP_SYSTEM_DESIGN.md) and
+[`PERSISTENT_SEARCH_TRANSPORT.md`](./docs/PERSISTENT_SEARCH_TRANSPORT.md).
 
 [Open the animated ForgeLoop evidence-first engineering flow](./docs/assets/diagrams/forgeloop-engineering-flow.html)
 
 ![ForgeLoop evidence-first engineering flow (animated SVG fallback)](./docs/assets/diagrams/forgeloop-engineering-flow.svg)
 
-The architecture flow is complemented by two focused, source-bound workflow
-diagrams. The [Verification Trust Flow source](./docs/diagrams/forgeloop-verification-trust-flow.workflow.json),
+Two focused, source-bound workflow
+diagrams complement it. The [Verification Trust Flow source](./docs/diagrams/forgeloop-verification-trust-flow.workflow.json),
 [animated explorer](./docs/assets/diagrams/forgeloop-verification-trust-flow.html),
 [SVG fallback](./docs/assets/diagrams/forgeloop-verification-trust-flow.svg),
 [receipt](./docs/assets/diagrams/forgeloop-verification-trust-flow.receipt.json),
 and [visual review](./docs/diagrams/reviews/forgeloop-verification-trust-flow.review.json)
-show why narrow verification is fail-closed. The [Code Attestation Chain
+show fail-closed verification. The [Code Attestation Chain
 source](./docs/diagrams/forgeloop-code-attestation-flow.workflow.json),
 [animated explorer](./docs/assets/diagrams/forgeloop-code-attestation-flow.html),
 [SVG fallback](./docs/assets/diagrams/forgeloop-code-attestation-flow.svg),

package/THIRD_PARTY_NOTICES.md

@@ -213,6 +213,17 @@ or make its prescriptive examples universal.
 
 ## Runtime dependencies with upstream notices
 
+### Microsoft tgrep
+
+- Project: [microsoft/tgrep](https://github.com/microsoft/tgrep).
+- License declared by the upstream project: MIT.
+- Use in this collection: the initially pinned native engine behind the
+  ForgeLoop Repository Index and normalized Repository Search contract.
+- Boundary: ForgeLoop verifies the exact release asset checksum and version
+  before managed installation. The executable is provisioned outside the npm
+  package; future redistribution must continue to include the MIT notice and
+  verify any changed upstream asset.
+
 ### Model Context Protocol SDK (MCP package only)
 
 - Packages: `@modelcontextprotocol/server` and `@modelcontextprotocol/client`

package/THREAT_MODEL.md

@@ -29,6 +29,27 @@ and an arbitrary external system in one transaction. Idempotency, durable
 intent, evidence, and reconciliation reduce duplicate-effect risk but do not
 provide a universal exactly-once guarantee.
 
+## Repository Index boundary
+
+The Repository Index is a local derived-cache and discovery boundary. Its
+native files are opaque inputs to the managed engine, never protocol evidence
+or completion authority. ForgeLoop owns the engine version, asset identity,
+index location, process lifecycle, and normalized result boundary.
+
+| Threat | Mitigation | Residual limitation | Test evidence |
+| --- | --- | --- | --- |
+| Supply-chain asset replacement | Version, archive SHA-256, and executable SHA-256 are pinned; the executable digest is checked before version execution and atomic installation; extracted version is verified | A separately privileged host can replace files after validation | `tests/repository-index-manifest.test.js`, `tests/repository-index-binary-manager.test.js` |
+| Archive path traversal | Archives are inspected for absolute, parent-traversing, and symbolic-link entries and extracted only into a temporary directory | Filesystem privileges can still alter the temporary directory outside the process boundary | `tests/repository-index-binary-manager.test.js` |
+| Malicious repository path or pattern shell injection | Native execution uses direct argument arrays with `shell: false`; request values are bounded and never interpolated into shell text | A hostile native engine remains an external process within the configured resource limits | `tests/repository-index-search.test.js`, `tests/repository-index-platform.test.js` |
+| Stale index | The tgrep watcher, strong first-use checks, process-local per-repository readiness cache, bounded recovery retry, status checks, doctor, explicit rebuild, and live/differential tests keep current working-tree visibility observable | A crash or native-engine defect can require an explicit rebuild | `tests/repository-index-hot-path.test.js`, `tests/repository-index-live.test.js`, `tests/repository-index-differential.test.js` |
+| Incorrect server ownership or PID reuse | Stop/start validates repository root, index path, server metadata, binary, liveness, and command line; it never kills by name or PID alone | A privileged process can rewrite all local metadata consistently | `tests/repository-index-server.test.js` |
+| Persistent host endpoint substitution or PID reuse | The CLI transport stores user-scoped state, verifies the exact host entrypoint and persistent-server marker, binds a scope identity to the handshake nonce, and performs bounded one-attempt recovery | A same-user or separately privileged process can deliberately deny the endpoint or rewrite every local artifact | `tests/persistent-transport.test.js`, `tests/persistent-transport-native.test.js` |
+| Persistent transport frame smuggling or resource exhaustion | Length-prefixed frames have explicit request/response byte limits; protocol version, IDs, methods, parameters, timeouts, and response IDs are validated before search dispatch | The local OS/user boundary still controls process scheduling and filesystem availability | `tests/persistent-transport.test.js` |
+| Persistent host privacy or fallback drift | State excludes repositories, history, matches, and evidence; the host calls canonical `searchRepository()` directly and `rg` is benchmark-only; public projections omit machine-local transport paths | A privileged same-user process can observe local IPC traffic | `docs/REPOSITORY_INDEX.md`, `docs/PERSISTENT_SEARCH_TRANSPORT.md`, `tests/persistent-transport.test.js` |
+| Sensitive match-content leakage | Search stays local; matches are not sent to telemetry or globally logged; metrics contain counts and timings rather than content | A caller can intentionally export its own local result | `tests/repository-index-search.test.js`, `tests/repository-index-integration.test.js` |
+| Machine-local path leakage | Normal CLI, Integration API, and MCP search/status projections omit absolute repository, index, state, and binary paths; matches are normalized relative paths | Explicit diagnostic commands may reveal local paths when requested | `tests/repository-index-privacy.test.js`, `tests/repository-index-hot-path.test.js`, `tests/repository-index-integration.test.js` |
+| Attacker-controlled or corrupt index files | Native index files remain opaque derived cache; corruption fails closed and is repaired by discard/rebuild, never interpreted as trusted truth | Native engine semantics and filesystem corruption remain outside ForgeLoop's parser | `tests/repository-index-migration.test.js`, `tests/repository-index-server.test.js` |
+
 ### Hardened durable-action threats (T-DURABLE-01 … T-DURABLE-13)
 
 | ID | Threat | Mitigation | Test evidence |

package/benchmarks/repository-index/README.md

@@ -0,0 +1,73 @@
+# Repository Index benchmarks
+
+This directory contains reproducible query inputs for the ForgeLoop Repository
+Index. It is an observational benchmark suite, not a release gate based on a
+universal speed target.
+
+Measure at least:
+
+- first-use setup and search;
+- warm server-backed selective query;
+- warm indexed selective query;
+- query after a file mutation;
+- high-match query;
+- low-match/no-match query.
+
+The hot-path runner also performs 100 repeated low-match queries by default
+for raw `tgrep`, the ForgeLoop search service, and `rg`. It reports total,
+mean, median, and p95 milliseconds for each series. Set
+`FORGELOOP_BENCHMARK_ITERATIONS` only when a different bounded sample size is
+needed.
+
+For every result, record the repository identifier and commit, platform,
+architecture, Node.js version, pinned tgrep version, query id, mode, duration,
+and observed match count. A result should have this shape:
+
+```json
+{
+  "schemaVersion": 1,
+  "repository": "local-fixture",
+  "commit": "working-tree",
+  "platform": "darwin",
+  "arch": "arm64",
+  "nodeVersion": "v26.8.1",
+  "tgrepVersion": "1.0.3",
+  "query": "selective-literal",
+  "mode": "warm",
+  "durationMs": 12,
+  "matches": 1
+}
+```
+
+An optional `rg` comparison is a test oracle only. It is never a runtime
+fallback and must not change the ForgeLoop search contract. Publish measured
+results with the fixture, command, and platform context; do not claim that
+indexed search is always faster or that search metrics imply token, cost, or
+agent-quality improvements.
+
+Run the hot-path benchmark against the exact native binary used by CI or the
+host:
+
+```bash
+FORGELOOP_TGREP_BINARY=/absolute/path/to/tgrep \
+  node benchmarks/repository-index/run-hot-path.mjs
+```
+
+The runner reports first-use, warm, post-mutation, and repeated low-match
+timings. It is observational and does not replace correctness, lifecycle, or
+cross-platform CI checks. `rg` is benchmark-only; it is never a ForgeLoop
+runtime fallback.
+
+The persistent-host benchmark compares the direct API, the user-scoped
+persistent transport, a fresh CLI process, raw tgrep, and optional `rg` over
+the same low-match workload. It records cold and warm timings, p95 values, and
+the separate Node process-startup component:
+
+```bash
+FORGELOOP_TGREP_BINARY=/absolute/path/to/tgrep \
+  node benchmarks/repository-index/run-persistent-transport.mjs
+```
+
+The benchmark starts an isolated host under a temporary user home and removes
+it after the run. A missing `rg` is reported as unavailable rather than being
+treated as a ForgeLoop failure.

package/benchmarks/repository-index/queries.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "queries": [
+    { "id": "selective-literal", "pattern": "repositoryFingerprint", "fixedStrings": true },
+    { "id": "regex", "pattern": "E_[A-Z_]+", "fixedStrings": false },
+    { "id": "case-insensitive", "pattern": "executionreceipt", "ignoreCase": true },
+    { "id": "word", "pattern": "receipt", "wordRegexp": true },
+    { "id": "javascript", "pattern": "export", "types": ["js"] },
+    { "id": "high-match", "pattern": "const", "fixedStrings": true },
+    { "id": "no-match", "pattern": "FORGELOOP_BENCHMARK_ABSENT", "fixedStrings": true }
+  ]
+}

package/benchmarks/repository-index/run-hot-path.mjs

@@ -0,0 +1,142 @@
+import { appendFile, cp, mkdtemp, readFile, rm } from "node:fs/promises";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { searchRepository } from "../../src/repository-index/search.js";
+import { stopRepositoryIndexServer } from "../../src/repository-index/server.js";
+import { getCanonicalRepositorySearchArgs, appendSearchFilters } from "../../src/repository-index/args.js";
+import { getTgrepIndexPath } from "../../src/repository-index/paths.js";
+import { createTgrepBinaryHandle, runTgrep } from "../../src/repository-index/process.js";
+
+const execFileAsync = promisify(execFile);
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+const fixtureRoot = path.join(packageRoot, "tests", "fixtures", "repository-index", "sample-repo");
+const binary = process.env.FORGELOOP_TGREP_BINARY;
+
+if (!binary || !path.isAbsolute(binary)) {
+  throw new Error("Set FORGELOOP_TGREP_BINARY to the absolute path of the pinned native tgrep binary");
+}
+const binaryHandle = createTgrepBinaryHandle(binary);
+
+const fixture = await mkdtemp(path.join(os.tmpdir(), "forgeloop-repository-index-benchmark-"));
+const queries = JSON.parse(await readFile(path.join(packageRoot, "benchmarks/repository-index/queries.json"), "utf8")).queries;
+const options = { packageRoot, binaryPath: binary, startupTimeoutMs: 30_000, commandTimeoutMs: 60_000 };
+const results = [];
+const repeatedIterations = Number.parseInt(process.env.FORGELOOP_BENCHMARK_ITERATIONS ?? "100", 10);
+if (!Number.isSafeInteger(repeatedIterations) || repeatedIterations < 1 || repeatedIterations > 1_000) {
+  throw new Error("FORGELOOP_BENCHMARK_ITERATIONS must be an integer from 1 to 1000");
+}
+
+const measure = async (query, mode, { record = true } = {}) => {
+  const startedAt = performance.now();
+  const result = await searchRepository(fixture, { ...options, ...query });
+  const durationMs = performance.now() - startedAt;
+  if (record) {
+    results.push({
+      query: query.id,
+      mode,
+      durationMs: Math.round(durationMs),
+      matches: result.matches.length,
+      nativeDurationMs: result.metrics.nativeDurationMs,
+      exitCode: result.metrics.exitCode,
+    });
+  }
+  return durationMs;
+};
+
+function percentile(values, fraction) {
+  const sorted = [...values].sort((left, right) => left - right);
+  const index = Math.min(sorted.length - 1, Math.ceil(sorted.length * fraction) - 1);
+  return sorted[index];
+}
+
+function summarize(durations) {
+  return {
+    iterations: durations.length,
+    totalMs: Math.round(durations.reduce((sum, value) => sum + value, 0)),
+    meanMs: Math.round(durations.reduce((sum, value) => sum + value, 0) / durations.length),
+    medianMs: Math.round(percentile(durations, 0.5)),
+    p95Ms: Math.round(percentile(durations, 0.95)),
+  };
+}
+
+async function measureRawTgrep(query) {
+  const args = [...getCanonicalRepositorySearchArgs({
+    indexPath: getTgrepIndexPath(fixture),
+    pattern: query.pattern,
+    options: query,
+  })];
+  appendSearchFilters(args, query);
+  args.push(fixture);
+  const startedAt = performance.now();
+  const result = await runTgrep({
+    binary: binaryHandle,
+    repoRoot: fixture,
+    args,
+    timeoutMs: options.commandTimeoutMs,
+    maxOutputBytes: 4 * 1024 * 1024,
+  });
+  if (![0, 1].includes(result.exitCode)) {
+    throw new Error(`raw tgrep benchmark query failed with exit code ${result.exitCode}: ${result.stderr}`);
+  }
+  return performance.now() - startedAt;
+}
+
+async function measureRipgrep(query) {
+  const startedAt = performance.now();
+  let result;
+  try {
+    result = await execFileAsync("rg", [
+      "--fixed-strings",
+      "--color", "never",
+      "--glob", "!.forgeloop/repository-index/**",
+      query.pattern,
+      fixture,
+    ], { maxBuffer: 4 * 1024 * 1024 });
+  } catch (error) {
+    if (error.code !== 1) throw error;
+  }
+  void result;
+  return performance.now() - startedAt;
+}
+
+async function measureRepeated(label, callback) {
+  const durations = [];
+  for (let index = 0; index < repeatedIterations; index += 1) durations.push(await callback());
+  return { label, ...summarize(durations) };
+}
+
+try {
+  await cp(fixtureRoot, fixture, { recursive: true });
+  await execFileAsync("git", ["init", "--quiet", fixture]);
+  await execFileAsync("git", ["-C", fixture, "add", "."]);
+  await measure({ id: "first-use", pattern: "alphaNeedle", fixedStrings: true }, "first-use");
+  for (const query of queries) await measure(query, "warm");
+  await appendFile(path.join(fixture, "src", "alpha.js"), "\nexport const benchmarkMutationNeedle = true;\n");
+  await measure({ id: "post-mutation", pattern: "benchmarkMutationNeedle", fixedStrings: true }, "post-mutation");
+  const lowMatchQuery = { id: "repeated-low-match", pattern: "FORGELOOP_BENCHMARK_ABSENT", fixedStrings: true };
+  const repeated = {
+    query: lowMatchQuery,
+    iterations: repeatedIterations,
+    rawTgrep: await measureRepeated("raw-tgrep", () => measureRawTgrep(lowMatchQuery)),
+    forgeloopSearch: await measureRepeated("forgeloop-search", () => measure(lowMatchQuery, "warm-repeated", { record: false })),
+    ripgrep: await measureRepeated("ripgrep", () => measureRipgrep(lowMatchQuery)),
+  };
+  console.log(JSON.stringify({
+    schemaVersion: 1,
+    repository: "repository-index-sample-fixture",
+    commit: "working-tree",
+    platform: process.platform,
+    arch: process.arch,
+    nodeVersion: process.version,
+    tgrepVersion: "1.0.3",
+    measurements: results,
+    repeatedLowMatch: repeated,
+  }, null, 2));
+} finally {
+  await stopRepositoryIndexServer(fixture, options).catch(() => {});
+  await rm(fixture, { recursive: true, force: true });
+}