@cassiomc1/forgeloop 1.10.2 → 1.11.0

package/docs/TROUBLESHOOTING.md

@@ -33,6 +33,10 @@ This guide provides symptom-first recovery procedures for common ForgeLoop proto
 - [Structural-quality verification reports a regression](#symptom-structural-quality-verification-reports-a-regression)
 - [Structural-quality provider is unavailable or invalid](#symptom-structural-quality-provider-is-unavailable-or-invalid)
 - [Structural-quality evidence is stale or incomparable](#symptom-structural-quality-evidence-is-stale-or-incomparable)
+- [Repository Index is not ready](#symptom-repository-index-is-not-ready)
+- [Repository search fails](#symptom-repository-search-fails)
+- [Persistent search host is unavailable](#symptom-persistent-search-host-is-unavailable)
+- [Persistent search host ownership is unverified or stale](#symptom-persistent-search-host-ownership-is-unverified-or-stale)
 - [Another harness cannot resume the task](#symptom-another-harness-cannot-resume)
 - [Task claim conflict or recovered task](#symptom-task-creation-blocked-by-a-write-claim-conflict-e_task_scope_conflict)
 - [Stable Error & Reason Code Reference](#stable-error-and-reason-codes)
@@ -1016,6 +1020,120 @@ Resolve the legitimate drift through the normal task lifecycle. Do not edit a
 baseline or evaluation by hand, and do not use a bundle as a reason to bypass
 current-cycle validation.
 
+### Symptom: Repository Index is not ready
+
+#### What it means
+
+`forgeloop index-status` did not report `READY`. For a Git repository the
+engine is mandatory, so `doctor` and repository-wide search remain unhealthy
+until the pinned binary, derived index, and ForgeLoop-owned watcher are
+verified.
+
+#### Inspect
+
+```bash
+forgeloop index-status --json
+forgeloop doctor --json
+```
+
+#### Safe recovery
+
+1. Run `forgeloop index-start --json` when the index is complete but the
+   watcher is down.
+2. Run `forgeloop index-setup --asset /absolute/path/to/pinned-asset.tar.gz`
+   for a missing engine or an air-gapped host.
+3. Run `forgeloop index-rebuild --json` after corruption or a confirmed stale
+   index.
+
+Never delete the whole `.forgeloop` directory and never stop a process by
+executable name. A status of `DEFERRED` for a non-Git protocol fixture is
+intentional and is not evidence that a real repository is healthy.
+
+### Symptom: Repository search fails
+
+#### What it means
+
+The provider-neutral search service rejected the request, could not verify the
+managed engine, or received an invalid native result. Search never falls back
+silently to `rg`, `grep`, or an arbitrary `PATH` executable.
+
+#### Inspect
+
+```bash
+forgeloop search "pattern" --json
+forgeloop index-status --json
+```
+
+Correct request bounds such as the pattern, filters, context, or `max-count`
+when the error is `E_REPOSITORY_INDEX_REQUEST_INVALID`. For
+`E_REPOSITORY_INDEX_OUTPUT_INVALID`, preserve the bounded diagnostic and
+rebuild; repeated malformed output indicates a pinned-engine regression.
+Native exit code `1` means no matches and is normalized to a successful empty
+ForgeLoop result. Native exit code `2` is an actual search failure.
+
+### Symptom: Persistent search host is unavailable
+
+#### What it means
+
+The CLI-only local transport could not connect to or start its user-scoped
+ForgeLoop host within the bounded startup/request timeout. This is a transport
+failure, not permission to bypass the mandatory Repository Index or switch to
+`rg`, `grep`, or an arbitrary executable.
+
+#### Inspect
+
+```bash
+forgeloop doctor --json
+forgeloop index-status --json
+forgeloop search "pattern" --json
+```
+
+#### Safe recovery
+
+Retry the search once after confirming that the current package is complete
+and the managed Repository Index reports `READY`. The client performs at most
+one bounded transport recovery attempt. If it still fails, preserve the
+structured error and follow the Repository Index recovery procedure above;
+transport recovery does not rebuild task state or completion evidence.
+
+`E_PERSISTENT_TRANSPORT_UNAVAILABLE`,
+`E_PERSISTENT_TRANSPORT_TIMEOUT`, and
+`E_PERSISTENT_TRANSPORT_START_FAILED` identify the local transport boundary.
+The canonical search error, if one is returned after a successful connection,
+must be diagnosed as a Repository Index or request error instead.
+
+### Symptom: Persistent search host ownership is unverified or stale
+
+#### What it means
+
+The local state or endpoint does not prove that the live process is the expected
+ForgeLoop persistent host. Common causes include a host from another package
+version, a process that exited while state remained, endpoint substitution, or
+PID reuse. A PID or process name alone is never sufficient ownership evidence.
+
+#### Inspect
+
+```bash
+forgeloop doctor --json
+forgeloop search "pattern" --json
+```
+
+The sanitized `persistentTransport` status reports only its public schema,
+state, running/owned flags, and protocol/package versions. It intentionally
+does not print endpoint, home, lock, repository, index, binary, or entrypoint
+paths.
+
+#### Safe recovery
+
+Allow the CLI's bounded recovery path to reconcile a stale or incompatible
+transport state. Explicit shutdown also requires a verified endpoint and nonce.
+If the status remains `OWNERSHIP_UNVERIFIED`, do not kill a PID or delete a
+whole `.forgeloop` directory; inspect the structured error and use the normal
+package/process recovery boundary. The relevant stable codes are
+`E_PERSISTENT_TRANSPORT_OWNERSHIP_UNVERIFIED`,
+`E_PERSISTENT_TRANSPORT_HOST_STALE`, and
+`E_PERSISTENT_TRANSPORT_PROTOCOL_MISMATCH`.
+
 ## Stable Error and Reason Codes
 
 <!-- BEGIN FORGELOOP GENERATED: public-error-codes -->
@@ -1162,6 +1280,16 @@ current-cycle validation.
 | `E_NATIVE_ADAPTER_TARGET_MISSING` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_NEW_POLICY_VIOLATION` | New executable policy violation detected that is not present in brownfield baseline. | Fix the violation before completing the task. |
 | `E_OBSERVATION_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
+| `E_PERSISTENT_TRANSPORT_FRAME_INVALID` | The local persistent-search byte stream did not contain a complete valid JSON frame. | Retry the bounded local request; inspect the host only if malformed frames recur. |
+| `E_PERSISTENT_TRANSPORT_FRAME_TOO_LARGE` | A persistent-search request or response exceeded its bounded frame limit. | Narrow the search request or inspect the host resource boundary; oversized frames are rejected. |
+| `E_PERSISTENT_TRANSPORT_HOST_STALE` | Persistent-search state points to a host process that is no longer running. | Retry the CLI search so ForgeLoop can remove only the verified stale host state and restart it. |
+| `E_PERSISTENT_TRANSPORT_INVALID_REQUEST` | A local persistent-search request is outside the versioned transport contract. | Use the supported ForgeLoop search command or update the compatible client and host together. |
+| `E_PERSISTENT_TRANSPORT_INVALID_RESPONSE` | The persistent-search host returned a response outside the versioned transport contract. | Retry once through the bounded recovery path; do not consume an unvalidated response. |
+| `E_PERSISTENT_TRANSPORT_OWNERSHIP_UNVERIFIED` | ForgeLoop could not prove that the process or endpoint belongs to its user-scoped persistent-search host. | Do not terminate the process; inspect the endpoint and retry after resolving the ownership conflict. |
+| `E_PERSISTENT_TRANSPORT_PROTOCOL_MISMATCH` | The persistent-search client and host do not agree on the supported protocol version. | ForgeLoop may replace only a verified compatible host; otherwise update the installed package and retry. |
+| `E_PERSISTENT_TRANSPORT_START_FAILED` | The user-scoped persistent-search host could not start or become ready within its bounded startup window. | Inspect the structured diagnostics and retry; direct integration APIs remain available without this optimization. |
+| `E_PERSISTENT_TRANSPORT_TIMEOUT` | A persistent-search connection, handshake, or request exceeded its bounded timeout. | Retry once through the ownership-checked recovery path and inspect host/index health if it persists. |
+| `E_PERSISTENT_TRANSPORT_UNAVAILABLE` | The user-scoped persistent-search endpoint was not reachable. | ForgeLoop starts one verified local host and retries once; persistent failure is reported without an rg fallback. |
 | `E_PHASE_CHRONOLOGY_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PHASE_PREREQUISITE_MISSING` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
 | `E_PHASE_TRANSITION_INVALID` | A ForgeLoop protocol validation or lifecycle condition was not satisfied. | Inspect the structured command result, correct the named artifact or prerequisite, then run forgeloop next --json. |
@@ -1208,6 +1336,25 @@ current-cycle validation.
 | `E_RECONCILE_REQUIREMENT_UNKNOWN` | The supplied check id and requirement text do not exactly match a contract verification item of type VERIFICATION. | Supply the exact id and requirement text of an existing contract verification item. |
 | `E_RECONCILE_UNSUPPORTED_DRIFT` | Work-state drift includes kinds other than REPOSITORY_CHANGED (contract or required-artifact drift). | Resolve contract or artifact drift through their dedicated recovery surfaces; reconcile-closure only refreshes repository fingerprint drift. |
 | `E_REPOSITORY_CHANGED` | The repository fingerprint (branch or HEAD) moved after the work-state checkpoint was recorded. | If the task objective is already satisfied in the current repository, run forgeloop reconcile-closure; otherwise resume from a checkpoint that matches the current repository. |
+| `E_REPOSITORY_INDEX_ENGINE_BINARY_CHECKSUM_MISMATCH` | The extracted or managed tgrep executable bytes do not match the pinned binary SHA-256 digest. | Run forgeloop index-setup or index-rebuild to repair the managed binary; do not run a mismatched executable. |
+| `E_REPOSITORY_INDEX_ENGINE_CHECKSUM_MISMATCH` | The tgrep archive or executable bytes do not match the pinned manifest SHA-256 digest. | Obtain the exact manifest asset and retry; do not install a checksum mismatch. |
+| `E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED` | The pinned tgrep release asset could not be downloaded or read. | Retry with network access or preload the exact manifest archive; never bypass provisioning verification. |
+| `E_REPOSITORY_INDEX_ENGINE_EXECUTION_FAILED` | A managed tgrep process could not be launched, completed, or stayed within its execution boundary. | Inspect the structured error and index status, then retry with the verified managed engine. |
+| `E_REPOSITORY_INDEX_ENGINE_EXTRACTION_FAILED` | The tgrep archive is malformed, unsafe, or could not be extracted to a temporary directory. | Use the exact supported archive and retry; unsafe paths and links are rejected. |
+| `E_REPOSITORY_INDEX_ENGINE_MISSING` | The managed tgrep executable is absent, unreadable, or has not been provisioned. | Run forgeloop index-setup or preload the exact manifest archive with --asset. |
+| `E_REPOSITORY_INDEX_ENGINE_VERSION_MISMATCH` | The executable reports a version different from the ForgeLoop-pinned tgrep version. | Provision the manifest-pinned tgrep release and retry; do not use an unpinned binary. |
+| `E_REPOSITORY_INDEX_INDEXING` | The repository index is still being built or reconciled and is not ready for the requested operation. | Wait for index-status to report READY, or use index-rebuild if the operation remains stuck. |
+| `E_REPOSITORY_INDEX_LOCK_UNSAFE` | A Repository Index operation lock is malformed, conflicting, or cannot be safely acquired. | Wait for a concurrent operation to finish and retry; use status or rebuild for a persistent lock failure. |
+| `E_REPOSITORY_INDEX_NOT_INITIALIZED` | The repository index has no complete derived index available for the requested operation. | Run forgeloop index-setup or forgeloop index-rebuild for the selected repository. |
+| `E_REPOSITORY_INDEX_OUTPUT_INVALID` | Native tgrep output did not match the bounded provider-neutral JSON contract. | Treat the result as unusable, inspect the engine, and rebuild or provision the pinned release. |
+| `E_REPOSITORY_INDEX_OUTPUT_LIMIT` | Managed tgrep output exceeded ForgeLoop's bounded process-output limit. | Narrow the search or resource policy and retry; oversized output is never promoted to a result. |
+| `E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED` | The current operating-system and architecture pair has no pinned tgrep release asset. | Use a supported platform or add a separately reviewed manifest asset; do not substitute a PATH executable. |
+| `E_REPOSITORY_INDEX_REBUILD_FAILED` | The derived repository index could not be rebuilt successfully. | Inspect the structured failure, resource policy, and repository paths, then retry index-rebuild. |
+| `E_REPOSITORY_INDEX_REQUEST_INVALID` | Repository Index command input is outside the bounded provider-neutral request contract. | Correct the pattern, path filters, context, or lifecycle options and retry the canonical command. |
+| `E_REPOSITORY_INDEX_SEARCH_FAILED` | The native tgrep search failed with an execution or provider error; no-match is not an error. | Inspect index-status and retry the query or rebuild the derived index; ForgeLoop does not fall back silently. |
+| `E_REPOSITORY_INDEX_SERVER_START_FAILED` | The ForgeLoop-owned tgrep watcher could not be started or did not become healthy. | Run index-status, inspect the structured reason, and retry index-start or index-rebuild. |
+| `E_REPOSITORY_INDEX_SERVER_STOP_FAILED` | The ForgeLoop-owned tgrep watcher could not be stopped or its ownership could not be proven. | Use index-status and retry the canonical stop operation; never terminate processes by name or PID alone. |
+| `E_REPOSITORY_INDEX_SERVER_UNHEALTHY` | Repository Index server, metadata, process identity, or index readiness validation failed. | Run index-status, then use index-rebuild after resolving the reported boundary. |
 | `E_RESPONSIBILITY_FROZEN_INPUT_DRIFT` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_RESPONSIBILITY_INVALID` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |
 | `E_RESPONSIBILITY_REQUIRED_CHECK_MISSING` | A ForgeLoop boundary, artifact, provider, or attestation validation condition was not satisfied. | Inspect the structured command result, correct the named boundary or artifact, then retry the canonical command. |

package/docs/UNIVERSAL_INTEGRATION.md

@@ -67,6 +67,36 @@ may be absent only when the canonical protocol marks it not applicable;
 presentation depth cannot change evidence, verification truth, authority,
 provenance, safety-floor, or validator-backed completion requirements.
 
+### Repository Search boundary
+
+The Integration API exposes direct, transport-neutral repository operations:
+
+```js
+import {
+  repositorySearch,
+  repositoryIndexStatus,
+} from "@cassiomc1/forgeloop/integration";
+
+const result = await repositorySearch({
+  projectPath: ".",
+  pattern: "needle",
+  fixedStrings: true,
+});
+
+const status = await repositoryIndexStatus({ projectPath: "." });
+```
+
+These operations call the canonical Repository Search service and require the
+managed Repository Index for supported Git repositories. The shell-facing CLI
+`search` command may use the user-scoped persistent local IPC host described in
+[`PERSISTENT_SEARCH_TRANSPORT.md`](./PERSISTENT_SEARCH_TRANSPORT.md), but that
+host is only a CLI startup/reuse optimization. Integration API and MCP callers
+do not use it, and no transport carries lifecycle, claims, receipts, evidence,
+or completion authority.
+
+See [`REPOSITORY_INDEX.md`](./REPOSITORY_INDEX.md) for the normalized search
+contract, tgrep management, status resource, and maintenance commands.
+
 ### Usage and efficiency boundary
 
 Create a context with an optional trusted provider:

package/docs/diagrams/README.md

@@ -87,3 +87,13 @@ These explanations are part of the JSON sources and generated explorers;
 matching textual fallbacks live in the README, revision-provider guide, and
 attestation guide. Re-render before renewing a visual review, then inspect
 the new output at desktop and narrow widths before binding the review hashes.
+
+The Repository Index and Persistent Search Transport are runtime discovery
+boundaries rather than lifecycle transitions. Their current CLI/API/MCP
+separation and local IPC sequence are documented in
+[`REPOSITORY_INDEX.md`](../REPOSITORY_INDEX.md) and
+[`PERSISTENT_SEARCH_TRANSPORT.md`](../PERSISTENT_SEARCH_TRANSPORT.md). They are
+intentionally not added as a fourth Archify workflow merely to increase the
+diagram count; the README hero provides the conceptual architecture overview,
+while these three governed visuals remain focused on lifecycle, verification,
+and attestation.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cassiomc1/forgeloop",
-  "version": "1.10.2",
+  "version": "1.11.0",
   "description": "Portable, verifiable engineering protocol for AI coding environments and developer workflows",
   "repository": {
     "type": "git",
@@ -24,6 +24,10 @@
     "schemas",
     "benchmarks/execution-profiles/*.json",
     "benchmarks/execution-profiles/README.md",
+    "benchmarks/repository-index/queries.json",
+    "benchmarks/repository-index/README.md",
+    "benchmarks/repository-index/run-hot-path.mjs",
+    "benchmarks/repository-index/run-persistent-transport.mjs",
     ".forgeloop/forgeloop.gitignore",
     "AGENTS.md",
     "CLAUDE.md",
@@ -72,6 +76,8 @@
     "docs/PLATFORM_ADAPTERS.md",
     "docs/AGENT_PROTOCOL_SUMMARY.md",
     "docs/EXECUTION_PROFILE_BENCHMARKS.md",
+    "docs/REPOSITORY_INDEX.md",
+    "docs/PERSISTENT_SEARCH_TRANSPORT.md",
     "docs/KNOWLEDGE_SOURCES.md",
     "scripts/generate-shell-completions.mjs",
     "scripts/generate-agent-protocol-summary.mjs",
@@ -80,6 +86,8 @@
     "scripts/validate-execution-profile-benchmarks.mjs",
     "scripts/report-execution-profile-outliers.mjs",
     "scripts/report-tail-interpretation.mjs",
+    "scripts/verify-tgrep-manifest.mjs",
+    "scripts/update-tgrep-manifest.mjs",
     "scripts/check-efficiency-regression.mjs",
     "scripts/lib/execution-profile-benchmark-io.mjs",
     "scripts/benchmark-cli-startup.mjs",
@@ -131,7 +139,8 @@
     "benchmark:profiles:tail-analysis": "node scripts/report-tail-interpretation.mjs",
     "benchmark:profiles:regression": "node scripts/check-efficiency-regression.mjs",
     "transactions:compact": "node scripts/compact-transactions.mjs",
-    "complexity:check": "node scripts/check-complexity.mjs"
+    "complexity:check": "node scripts/check-complexity.mjs",
+    "repository-index:manifest": "node scripts/verify-tgrep-manifest.mjs"
   },
   "devDependencies": {
     "c8": "^12.0.0",

package/scripts/update-tgrep-manifest.mjs

@@ -0,0 +1,86 @@
+import { execFile as nodeExecFile } from "node:child_process";
+import { mkdtemp, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { validateTgrepManifest } from "../src/repository-index/manifest.js";
+import { sha256File, validateArchiveEntry } from "../src/repository-index/binary-manager.js";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const manifestPath = path.join(packageRoot, "src", "repository-index", "tgrep-manifest.json");
+const args = process.argv.slice(2);
+const assetDirIndex = args.indexOf("--asset-dir");
+const assetDir = assetDirIndex >= 0 ? args[assetDirIndex + 1] : null;
+const shouldWrite = args.includes("--write");
+
+if (!assetDir || !path.isAbsolute(assetDir) || !shouldWrite) {
+  console.error("Usage: node scripts/update-tgrep-manifest.mjs --asset-dir /absolute/release-assets --write");
+  process.exit(1);
+}
+
+const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+validateTgrepManifest(manifest);
+
+function execFile(file, args, options = {}) {
+  return new Promise((resolve, reject) => {
+    nodeExecFile(file, args, { shell: false, ...options }, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+      resolve({ stdout, stderr });
+    });
+  });
+}
+
+async function listArchiveEntries(archivePath, archive) {
+  const command = archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
+  const args = command === "unzip" ? ["-Z1", archivePath] : ["-tf", archivePath];
+  const result = await execFile(command, args, { maxBuffer: 2 * 1024 * 1024 });
+  return result.stdout.split(/\r?\n/).filter(Boolean).map(validateArchiveEntry);
+}
+
+async function extractBinary(assetPath, asset, destination) {
+  const entries = await listArchiveEntries(assetPath, asset.archive);
+  if (!entries.some((entry) => path.posix.basename(entry) === asset.binaryName)) {
+    throw new Error(`archive does not contain ${asset.binaryName}`);
+  }
+  const command = asset.archive === "zip" && process.platform !== "win32" ? "unzip" : "tar";
+  const args = command === "unzip"
+    ? ["-q", assetPath, "-d", destination]
+    : ["-xf", assetPath, "-C", destination];
+  await execFile(command, args, { maxBuffer: 2 * 1024 * 1024 });
+
+  const found = [];
+  async function visit(directory) {
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const entryPath = path.join(directory, entry.name);
+      if (entry.isSymbolicLink()) throw new Error(`archive extracted a symbolic link: ${entry.name}`);
+      if (entry.isDirectory()) await visit(entryPath);
+      else if (entry.isFile() && entry.name === asset.binaryName) found.push(entryPath);
+    }
+  }
+  await visit(destination);
+  if (found.length !== 1) throw new Error(`expected exactly one ${asset.binaryName}, found ${found.length}`);
+  return found[0];
+}
+
+for (const asset of Object.values(manifest.assets)) {
+  const assetPath = path.join(assetDir, asset.assetName);
+  const info = await stat(assetPath);
+  if (!info.isFile()) throw new Error(`asset is not a regular file: ${assetPath}`);
+  asset.sha256 = await sha256File(assetPath);
+  const extractionDirectory = await mkdtemp(path.join(os.tmpdir(), "forgeloop-tgrep-manifest-"));
+  try {
+    const extractedBinary = await extractBinary(assetPath, asset, extractionDirectory);
+    asset.binarySha256 = await sha256File(extractedBinary);
+  } finally {
+    await rm(extractionDirectory, { recursive: true, force: true });
+  }
+}
+validateTgrepManifest(manifest);
+await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
+console.log(`updated ${manifestPath}`);

package/scripts/verify-tgrep-manifest.mjs

@@ -0,0 +1,17 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { validateTgrepManifest } from "../src/repository-index/manifest.js";
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+const manifestPath = path.join(packageRoot, "src", "repository-index", "tgrep-manifest.json");
+
+try {
+  const value = JSON.parse(await readFile(manifestPath, "utf8"));
+  validateTgrepManifest(value);
+  console.log(`valid tgrep manifest: ${value.engine} ${value.version} (${Object.keys(value.assets).length} assets)`);
+} catch (error) {
+  console.error(`invalid tgrep manifest: ${error.message}`);
+  process.exitCode = 1;
+}

package/src/cli.js

@@ -85,6 +85,11 @@ import { formatAttestationCreateResult } from "./commands/attestation-create.js"
 import { formatAttestationVerifyResult } from "./commands/attestation-verify.js";
 import { formatAttestationStatusResult } from "./commands/attestation-status.js";
 import { formatAttestationVerifyRangeResult } from "./commands/attestation-verify-range.js";
+import {
+  formatRepositoryIndexResult,
+  formatRepositoryIndexStatus,
+  formatSearchResult,
+} from "./commands/repository-index.js";
 import { defaultCommandInputValues, validateForgeLoopCommandInput } from "./core/command-input.js";
 import { COMMAND_EXECUTORS } from "./core/command-executors.js";
 import { resolveTarget } from "./core/filesystem.js";
@@ -368,6 +373,36 @@ export const COMMAND_HANDLERS = Object.freeze({
     }
     return result.ok ? 0 : 1;
   },
+  "index-setup": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-setup"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexResult);
+    return 0;
+  },
+  "index-start": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-start"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexResult);
+    return 0;
+  },
+  "index-stop": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-stop"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexResult);
+    return 0;
+  },
+  "index-status": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-status"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexStatus);
+    return 0;
+  },
+  "index-rebuild": async ({ target, packageRoot, options }) => {
+    const { result } = await COMMAND_EXECUTORS["index-rebuild"]({ target, packageRoot, options });
+    renderJsonOr(options, result, formatRepositoryIndexResult);
+    return 0;
+  },
+  search: async ({ target, packageRoot, options }) => {
+    const { result, exitCode } = await COMMAND_EXECUTORS.search({ target, packageRoot, options, transport: "cli" });
+    renderJsonOr(options, result, formatSearchResult);
+    return exitCode;
+  },
   route: async ({ target, packageRoot, options }) => {
     const { result } = await COMMAND_EXECUTORS.route({ target, packageRoot, options });
     renderJsonOr(options, result, formatRouteResult);

package/src/commands/doctor.js

@@ -5,6 +5,10 @@ import { createEvidence } from "../core/evidence.js";
 import { LAYOUT_VERSION } from "../core/target-layout.js";
 import { inspectNativeAdapter, validateNativeAdapterTargets } from "../core/native-adapters.js";
 import { findIncompleteTransactions, recoverIncompleteTransactions } from "../core/transaction.js";
+import { isRepositoryCandidate } from "../repository-index/lifecycle.js";
+import { getRepositoryIndexStatus, sanitizeRepositoryIndexStatus } from "../repository-index/status.js";
+import { searchRepository } from "../repository-index/search.js";
+import { getPersistentTransportStatus } from "../persistent-transport/client.js";
 
 function finding(code, severity, relativePath, message, remediation = null, evidence = null) {
   const evidenceRecord = evidence && typeof evidence === "object"
@@ -114,7 +118,69 @@ async function adoptAdapters({ target, manifest, adoptPaths, findings }) {
   return nextManifest;
 }
 
-export async function runDoctor({ target, packageRoot, adoptPaths = [], strict = false, fix = false }) {
+async function inspectRepositoryIndexForDoctor({ target, packageRoot, repositoryIndex, repositoryIndexOptions, findings }) {
+  const persistentTransport = await getPersistentTransportStatus({ homeDirectory: repositoryIndexOptions?.homeDirectory });
+  if (!repositoryIndex) return { status: "DISABLED", required: false, persistentTransport };
+  if (!(await isRepositoryCandidate(target))) {
+    return { status: "DEFERRED", required: true, reason: "target is not a Git repository", persistentTransport };
+  }
+
+  const status = await getRepositoryIndexStatus(target, { packageRoot, ...repositoryIndexOptions, includeLocalPaths: true });
+  const publicStatus = sanitizeRepositoryIndexStatus(status);
+  const result = {
+    status: publicStatus.health,
+    required: true,
+    engine: publicStatus.engine,
+    engineVersion: publicStatus.engineVersion,
+    indexPath: ".forgeloop/repository-index/tgrep",
+    server: publicStatus.server,
+    diagnostics: publicStatus.diagnostics,
+    persistentTransport,
+  };
+  if (status.health === "READY") {
+    try {
+      const smoke = await searchRepository(target, {
+        ...repositoryIndexOptions,
+        packageRoot,
+        pattern: "__FORGELOOP_DOCTOR_INDEX_SMOKE__",
+        fixedStrings: true,
+        maxCount: 1,
+      });
+      result.smokeSearch = {
+        status: "OK",
+        matchCount: smoke.matches.length,
+        nativeExitCode: smoke.metrics.exitCode,
+      };
+    } catch (error) {
+      result.smokeSearch = {
+        status: "ERROR",
+        code: error.code ?? "E_REPOSITORY_INDEX_SEARCH_FAILED",
+        message: error.message,
+      };
+      findings.push(finding(
+        error.code ?? "E_REPOSITORY_INDEX_SEARCH_FAILED",
+        "error",
+        ".forgeloop/repository-index",
+        `Repository Index smoke search failed: ${error.message}`,
+        "Run forgeloop index-status --json, then index-rebuild if the managed search service is unhealthy.",
+        error.message,
+      ));
+    }
+  }
+  if (status.health !== "READY") {
+    findings.push(finding(
+      publicStatus.diagnostics?.[0]?.code ?? "E_REPOSITORY_INDEX_SERVER_UNHEALTHY",
+      "error",
+      ".forgeloop/repository-index",
+      `Repository Index is ${status.health}; ${publicStatus.diagnostics?.[0]?.message ?? "native index health is not ready"}`,
+      "Run forgeloop index-setup or forgeloop index-rebuild with an approved managed tgrep asset.",
+      publicStatus,
+    ));
+  }
+  return result;
+}
+
+export async function runDoctor({ target, packageRoot, adoptPaths = [], strict = false, fix = false, repositoryIndex, repositoryIndexOptions }) {
   const findings = [];
   let incompleteTransactions = await findIncompleteTransactions(target);
   if (fix && incompleteTransactions.some((transaction) => transaction.status === "COMMITTING")) {
@@ -318,11 +384,20 @@ export async function runDoctor({ target, packageRoot, adoptPaths = [], strict =
     await writeManifest(target, manifest);
   }
 
+  const repositoryIndexResult = await inspectRepositoryIndexForDoctor({
+    target,
+    packageRoot,
+    repositoryIndex,
+    repositoryIndexOptions,
+    findings,
+  });
+
   const ok = findings.every((item) => item.severity !== "error")
     && (!strict || findings.every((item) => item.severity !== "warning"));
   return {
     ok,
     findings,
+    repositoryIndex: repositoryIndexResult,
     evidence: [createEvidence({
       kind: "OBSERVED",
       source: "ForgeLoop doctor",

package/src/commands/index-rebuild.js

@@ -0,0 +1 @@
+export { runRepositoryIndexRebuild, formatRepositoryIndexResult } from "./repository-index.js";

package/src/commands/index-setup.js

@@ -0,0 +1 @@
+export { runRepositoryIndexSetup, formatRepositoryIndexResult } from "./repository-index.js";

package/src/commands/index-start.js

@@ -0,0 +1 @@
+export { runRepositoryIndexStart, formatRepositoryIndexResult } from "./repository-index.js";

package/src/commands/index-status.js

@@ -0,0 +1 @@
+export { runRepositoryIndexStatus, formatRepositoryIndexStatus } from "./repository-index.js";

package/src/commands/index-stop.js

@@ -0,0 +1 @@
+export { runRepositoryIndexStop, formatRepositoryIndexResult } from "./repository-index.js";

package/src/commands/init.js

@@ -9,6 +9,8 @@ import { readTemplateEntries } from "../core/templates.js";
 import { PROJECT_ARTIFACT_PATHS } from "../core/task-paths.js";
 import { isKitPath } from "../core/target-layout.js";
 import { E_INIT_KIT_CONFLICT, E_POLICY_INITIALIZATION_FAILED } from "../core/error-codes.js";
+import { isRepositoryCandidate } from "../repository-index/lifecycle.js";
+import { setupRepositoryIndex } from "../repository-index/server.js";
 
 // Compatibility re-exports: the canonical semantic definitions live in
 // src/core/error-codes.js; this keeps existing import paths working while
@@ -107,6 +109,31 @@ function kitConflictError(relativePath) {
   return error;
 }
 
+async function prepareRepositoryIndexForInit({ target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions, actions }) {
+  if (!repositoryIndex) return { status: "DISABLED", required: false };
+  if (!(await isRepositoryCandidate(target))) {
+    return { status: "DEFERRED", required: true, reason: "target is not a Git repository" };
+  }
+  if (dryRun) {
+    return {
+      status: "WOULD_SETUP",
+      required: true,
+      reason: "dry-run does not provision or execute the native index engine",
+    };
+  }
+
+  const setup = await setupRepositoryIndex(target, { ...repositoryIndexOptions, packageRoot });
+  actions.push({ action: "repository-index-ready", path: ".forgeloop/repository-index", reason: "managed tgrep index and watcher are ready" });
+  return {
+    status: "READY",
+    required: true,
+    health: setup.status?.health ?? "READY",
+    engine: setup.status?.engine ?? "tgrep",
+    engineVersion: setup.status?.engineVersion ?? null,
+    server: setup.status?.server ?? null,
+  };
+}
+
 /**
  * Initializes a target project with the ForgeLoop kit and executable-policy
  * bootstrap, committing manifest authority LAST.
@@ -152,6 +179,8 @@ export async function runInit({
   packageRoot,
   packageVersion,
   hooks = {},
+  repositoryIndex,
+  repositoryIndexOptions,
 } = {}) {
   const entries = await readTemplateEntries(packageRoot);
   const existingManifest = await readManifest(target);
@@ -332,6 +361,15 @@ export async function runInit({
     }
   }
 
+  const repositoryIndexResult = await prepareRepositoryIndexForInit({
+    target,
+    dryRun,
+    packageRoot,
+    repositoryIndex,
+    repositoryIndexOptions,
+    actions,
+  });
+
   // 10. Commit manifest authority LAST: successful initialization is only
   // real once the manifest exists.
   if (hooks.beforeManifestWrite) {
@@ -343,5 +381,5 @@ export async function runInit({
   }
   await writeManifest(target, manifest, { dryRun });
 
-  return { actions, manifest };
+  return { actions, manifest, repositoryIndex: repositoryIndexResult };
 }