@cassiomc1/forgeloop 1.10.2 → 1.11.0

package/src/commands/repository-index.js

@@ -0,0 +1,111 @@
+import { rebuildRepositoryIndex, setupRepositoryIndex, startRepositoryIndexServer, stopRepositoryIndexServer } from "../repository-index/server.js";
+import { searchRepository } from "../repository-index/search.js";
+import { formatRepositoryIndexStatus, getRepositoryIndexStatus, sanitizeRepositoryIndexStatus } from "../repository-index/status.js";
+import { searchViaPersistentTransport } from "../persistent-transport/client.js";
+
+function sanitizeLifecycleResult(result) {
+  const { status, indexed, ...rest } = result ?? {};
+  const publicIndexed = indexed && typeof indexed === "object"
+    ? Object.fromEntries(Object.entries(indexed).filter(([key]) => !["root_path", "rootPath", "indexPath", "repositoryRoot"].includes(key)))
+    : indexed;
+  return {
+    ...rest,
+    ...(status ? { status: sanitizeRepositoryIndexStatus(status) } : {}),
+    ...(indexed ? { indexed: publicIndexed } : {}),
+  };
+}
+
+function nativeOptions(options, packageRoot) {
+  return {
+    packageRoot,
+    assetPath: options.assetPath ?? undefined,
+    binaryPath: options.binaryPath ?? undefined,
+    homeDirectory: options.homeDirectory ?? undefined,
+    force: options.force === true,
+    config: options.indexConfig ?? undefined,
+  };
+}
+
+export async function runRepositoryIndexSetup({ target, packageRoot, options = {} } = {}) {
+  const native = nativeOptions(options, packageRoot);
+  const result = await setupRepositoryIndex(target, native);
+  return sanitizeLifecycleResult({ ...result, status: result.status ?? await getRepositoryIndexStatus(target, { ...native, packageRoot, includeLocalPaths: true }) });
+}
+
+export async function runRepositoryIndexStart({ target, packageRoot, options = {} } = {}) {
+  const native = nativeOptions(options, packageRoot);
+  const result = await startRepositoryIndexServer(target, native);
+  return sanitizeLifecycleResult({ ...result, status: result.status ?? await getRepositoryIndexStatus(target, { ...native, packageRoot, includeLocalPaths: true }) });
+}
+
+export async function runRepositoryIndexStop({ target, packageRoot, options = {} } = {}) {
+  const native = nativeOptions(options, packageRoot);
+  const result = await stopRepositoryIndexServer(target, native);
+  return sanitizeLifecycleResult({ ...result, status: await getRepositoryIndexStatus(target, { ...native, packageRoot, skipNativeStatus: true }) });
+}
+
+export async function runRepositoryIndexStatus({ target, packageRoot, options = {} } = {}) {
+  return getRepositoryIndexStatus(target, { ...nativeOptions(options, packageRoot), packageRoot });
+}
+
+export async function runRepositoryIndexRebuild({ target, packageRoot, options = {} } = {}) {
+  const native = nativeOptions(options, packageRoot);
+  const result = await rebuildRepositoryIndex(target, native);
+  const status = result.status ?? await getRepositoryIndexStatus(target, { ...native, packageRoot });
+  const smoke = await searchRepository(target, {
+    ...native,
+    pattern: "__FORGELOOP_INDEX_REBUILD_SMOKE__",
+    fixedStrings: true,
+    maxCount: 1,
+  });
+  return sanitizeLifecycleResult({
+    ...result,
+    status: sanitizeRepositoryIndexStatus(status),
+    smokeSearch: {
+      status: "OK",
+      matchCount: smoke.matches.length,
+      nativeExitCode: smoke.metrics.exitCode,
+    },
+  });
+}
+
+export async function runSearch({ target, packageRoot, options = {}, transport = "integration" } = {}) {
+  if (transport === "cli") {
+    return searchViaPersistentTransport(target, options, {
+      homeDirectory: options.homeDirectory,
+      idleTimeoutMs: options.persistentTransportIdleTimeoutMs,
+      startupTimeoutMs: options.persistentTransportStartupTimeoutMs,
+      requestTimeoutMs: options.persistentTransportRequestTimeoutMs,
+      env: options.env,
+    });
+  }
+  return searchRepository(target, {
+    ...options,
+    packageRoot,
+    pattern: options.pattern,
+    globs: options.globs ?? [],
+    types: options.types ?? [],
+  });
+}
+
+export function formatRepositoryIndexResult(result) {
+  const status = result.status ?? result;
+  const lines = [
+    `Repository Index: ${status.health ?? "READY"}`,
+    `Engine: ${status.engine ?? "tgrep"} ${status.engineVersion ?? "unknown"}`,
+    `Index: ${status.indexPath ?? "unknown"}`,
+    `Server: ${status.server?.running ? `running (pid ${status.server.pid ?? "unknown"})` : "not running"}`,
+  ];
+  if (result.rebuilt) lines.push("Rebuilt: yes");
+  if (result.setup) lines.push(`Setup: ${result.rebuilt ? "rebuilt" : "reused"}`);
+  if (result.stopped !== undefined) lines.push(`Stopped: ${result.stopped ? "yes" : "no"}`);
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatSearchResult(result) {
+  if (result.query.filesWithMatches) return `${(result.files ?? []).join("\n")}${result.files?.length ? "\n" : "no matches\n"}`;
+  const lines = (result.matches ?? []).map((match) => `${match.path}:${match.line}${match.column ? `:${match.column}` : ""}:${match.text}`);
+  return `${lines.join("\n")}${lines.length ? "\n" : "no matches\n"}`;
+}
+
+export { formatRepositoryIndexStatus };

package/src/commands/search.js

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

package/src/commands/update.js

@@ -10,6 +10,8 @@ import {
 } from "../core/manifest.js";
 import { readTemplateEntries } from "../core/templates.js";
 import { isNativeAdapterPath, LAYOUT_VERSION, LEGACY_PROFILE_PATH } from "../core/target-layout.js";
+import { isRepositoryCandidate } from "../repository-index/lifecycle.js";
+import { setupRepositoryIndex } from "../repository-index/server.js";
 
 const LEGACY_CLEANUP_DIRECTORIES = Object.freeze(["ENG", "schemas"]);
 
@@ -295,7 +297,32 @@ async function migrateLegacyLayout({ target, dryRun, packageVersion, currentMani
   return { actions, conflicts, manifest: nextManifest };
 }
 
-export async function runUpdate({ target, dryRun, packageRoot, packageVersion, hooks = {} }) {
+async function attachRepositoryIndexResult(result, { target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions = {} }) {
+  if (!repositoryIndex) return result;
+  if (!(await isRepositoryCandidate(target))) {
+    return { ...result, repositoryIndex: { status: "DEFERRED", required: true, reason: "target is not a Git repository" } };
+  }
+  if (dryRun) {
+    return { ...result, repositoryIndex: { status: "WOULD_SETUP", required: true, reason: "dry-run does not provision or execute the native index engine" } };
+  }
+  if (result.conflicts?.length > 0) {
+    return { ...result, repositoryIndex: { status: "BLOCKED", required: true, reason: "update conflicts must be resolved before index maintenance" } };
+  }
+  const setup = await setupRepositoryIndex(target, { ...repositoryIndexOptions, packageRoot });
+  return {
+    ...result,
+    repositoryIndex: {
+      status: "READY",
+      required: true,
+      health: setup.status?.health ?? "READY",
+      engine: setup.status?.engine ?? "tgrep",
+      engineVersion: setup.status?.engineVersion ?? null,
+      server: setup.status?.server ?? null,
+    },
+  };
+}
+
+export async function runUpdate({ target, dryRun, packageRoot, packageVersion, hooks = {}, repositoryIndex, repositoryIndexOptions }) {
   const currentManifest = await readManifest(target);
   if (!currentManifest) {
     throw new Error("No .forgeloop/manifest.json found; run forgeloop init first.");
@@ -303,7 +330,8 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion, h
 
   const entries = await readTemplateEntries(packageRoot);
   if ((currentManifest.layoutVersion ?? 1) < LAYOUT_VERSION) {
-    return migrateLegacyLayout({ target, dryRun, packageVersion, currentManifest, entries, hooks });
+    const result = await migrateLegacyLayout({ target, dryRun, packageVersion, currentManifest, entries, hooks });
+    return attachRepositoryIndexResult(result, { target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions });
   }
 
   const nextManifest = structuredClone(currentManifest);
@@ -405,7 +433,7 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion, h
   }
 
   if (conflicts.length > 0) {
-    return { actions, conflicts, manifest: currentManifest };
+    return attachRepositoryIndexResult({ actions, conflicts, manifest: currentManifest }, { target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions });
   }
 
   for (const relativePath of Object.keys(nextManifest.files)) {
@@ -423,5 +451,5 @@ export async function runUpdate({ target, dryRun, packageRoot, packageVersion, h
   nextManifest.packageVersion = packageVersion;
   await writeManifest(target, nextManifest, { dryRun });
   await cleanupLegacyFiles({ target, dryRun, cleanupFiles, cleanupDirectories, hooks, actions, conflicts });
-  return { actions, conflicts, manifest: nextManifest };
+  return attachRepositoryIndexResult({ actions, conflicts, manifest: nextManifest }, { target, dryRun, packageRoot, repositoryIndex, repositoryIndexOptions });
 }

package/src/core/cli-command-definitions.js

@@ -81,7 +81,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     }),
     writes: [".forgeloop/*", "AGENTS.md", "CLAUDE.md", ".cursor/rules/project-loop.mdc", ".github/copilot-instructions.md"],
     removes: [],
-    mayExecuteExternalProcess: false,
+    mayExecuteExternalProcess: true,
     description: "Initializes a target project directory with ForgeLoop discovery adapters, schemas, and templates.",
   }),
   doctor: Object.freeze({
@@ -97,9 +97,103 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     }),
     writes: [".forgeloop/.manifest.json"],
     removes: [],
-    mayExecuteExternalProcess: false,
+    mayExecuteExternalProcess: true,
     description: "Diagnoses project health, discovers adapters, and optionally repairs missing template files.",
   }),
+  "index-setup": Object.freeze({
+    name: "index-setup",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--asset": Object.freeze({ targetKey: "assetPath", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--asset requires a local archive path", description: "use a preloaded pinned tgrep archive instead of downloading" }),
+      "--force": Object.freeze({ targetKey: "force", parseType: "boolean", takesValue: false, description: "rebuild the repository index even when metadata is current" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit repository-index setup as JSON" }),
+    }),
+    writes: [".forgeloop/repository-index/*"],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Provisions the pinned tgrep engine, builds the repository index, and starts its owned watcher.",
+  }),
+  "index-start": Object.freeze({
+    name: "index-start",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit repository-index start as JSON" }),
+    }),
+    writes: [".forgeloop/repository-index/engine-state.json"],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Starts the owned tgrep repository-index watcher after an index has been built.",
+  }),
+  "index-stop": Object.freeze({
+    name: "index-stop",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit repository-index stop as JSON" }),
+    }),
+    writes: [],
+    removes: [".forgeloop/repository-index/serve.json", ".forgeloop/repository-index/engine-state.json"],
+    mayExecuteExternalProcess: true,
+    description: "Stops only a tgrep server whose process identity is provably owned by ForgeLoop.",
+  }),
+  "index-status": Object.freeze({
+    name: "index-status",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit repository-index health as JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Reports provider-neutral repository-index health, metadata, and owned-server status.",
+  }),
+  "index-rebuild": Object.freeze({
+    name: "index-rebuild",
+    category: "project-maintenance",
+    mutation: "MUTATING",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "--asset": Object.freeze({ targetKey: "assetPath", parseType: "string", takesValue: true, valueName: "path", missingValueMessage: "--asset requires a local archive path", description: "use a preloaded pinned tgrep archive instead of downloading" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit repository-index rebuild as JSON" }),
+    }),
+    writes: [".forgeloop/repository-index/*"],
+    removes: [".forgeloop/repository-index/tgrep/*"],
+    mayExecuteExternalProcess: true,
+    description: "Atomically rebuilds the repository index and restarts its owned watcher.",
+  }),
+  search: Object.freeze({
+    name: "search",
+    category: "diagnostics",
+    mutation: "READ_ONLY",
+    options: Object.freeze({
+      ...CLI_COMMON_OPTIONS,
+      "<pattern>": Object.freeze({ targetKey: "pattern", parseType: "string", takesValue: true, isPositional: true, valueName: "pattern", description: "regular expression or literal search pattern" }),
+      "--glob": Object.freeze({ targetKey: "globs", parseType: "string", takesValue: true, repeatable: true, valueName: "glob", missingValueMessage: "--glob requires a pattern", description: "include files matching a glob" }),
+      "--type": Object.freeze({ targetKey: "types", parseType: "string", takesValue: true, repeatable: true, valueName: "type", missingValueMessage: "--type requires a file type", description: "include files of a tgrep type" }),
+      "--fixed-strings": Object.freeze({ targetKey: "fixedStrings", parseType: "boolean", takesValue: false, description: "treat the pattern as a literal string" }),
+      "--ignore-case": Object.freeze({ targetKey: "ignoreCase", parseType: "boolean", takesValue: false, description: "search case-insensitively" }),
+      "--smart-case": Object.freeze({ targetKey: "smartCase", parseType: "boolean", takesValue: false, description: "use case-insensitive search only for lowercase patterns" }),
+      "--word-regexp": Object.freeze({ targetKey: "wordRegexp", parseType: "boolean", takesValue: false, aliases: ["--word"], description: "match whole words only" }),
+      "--context": Object.freeze({ targetKey: "context", parseType: "non-negative-integer", takesValue: true, valueName: "lines", missingValueMessage: "--context requires a non-negative integer", description: "lines of context before and after matches" }),
+      "--before-context": Object.freeze({ targetKey: "beforeContext", parseType: "non-negative-integer", takesValue: true, valueName: "lines", missingValueMessage: "--before-context requires a non-negative integer", description: "lines of context before matches" }),
+      "--after-context": Object.freeze({ targetKey: "afterContext", parseType: "non-negative-integer", takesValue: true, valueName: "lines", missingValueMessage: "--after-context requires a non-negative integer", description: "lines of context after matches" }),
+      "--max-count": Object.freeze({ targetKey: "maxCount", parseType: "non-negative-integer", takesValue: true, valueName: "number", missingValueMessage: "--max-count requires a positive integer", description: "maximum matches per file" }),
+      "--files-with-matches": Object.freeze({ targetKey: "filesWithMatches", parseType: "boolean", takesValue: false, description: "return matching file paths only" }),
+      "--stats": Object.freeze({ targetKey: "stats", parseType: "boolean", takesValue: false, description: "include observed native search statistics" }),
+      "--json": Object.freeze({ targetKey: "json", parseType: "boolean", takesValue: false, description: "emit normalized provider-neutral search JSON" }),
+    }),
+    writes: [],
+    removes: [],
+    mayExecuteExternalProcess: true,
+    description: "Searches the ForgeLoop repository index through the provider-neutral search contract.",
+  }),
   update: Object.freeze({
     name: "update",
     category: "project-maintenance",
@@ -110,7 +204,7 @@ export const CLI_COMMAND_DEFINITIONS = Object.freeze({
     }),
     writes: [".forgeloop/*", "AGENTS.md", "CLAUDE.md", ".cursor/rules/project-loop.mdc", ".github/copilot-instructions.md"],
     removes: [],
-    mayExecuteExternalProcess: false,
+    mayExecuteExternalProcess: true,
     description: "Updates installed templates, discovery adapters, and canonical engineering guides to the latest version.",
   }),
   activate: Object.freeze({

package/src/core/command-executors.js

@@ -82,6 +82,14 @@ import { runAttestationVerify } from "../commands/attestation-verify.js";
 import { runAttestationStatus } from "../commands/attestation-status.js";
 import { runAttestationVerifyRange } from "../commands/attestation-verify-range.js";
 import { exitCodeForAttestationResult } from "./exit-codes.js";
+import {
+  runRepositoryIndexRebuild,
+  runRepositoryIndexSetup,
+  runRepositoryIndexStart,
+  runRepositoryIndexStatus,
+  runRepositoryIndexStop,
+  runSearch,
+} from "../commands/repository-index.js";
 
 /**
  * Canonical transport-neutral command executors.
@@ -100,7 +108,7 @@ export const COMMAND_EXECUTORS = {
     exitCode: 0,
   }),
   init: async ({ target, packageRoot, packageVersion, options }) => ({
-    result: await runInit({ target, dryRun: options.dryRun, packageRoot, packageVersion }),
+    result: await runInit({ target, dryRun: options.dryRun, packageRoot, packageVersion, repositoryIndex: true }),
     exitCode: 0,
   }),
   doctor: async ({ target, packageRoot, options }) => {
@@ -110,6 +118,7 @@ export const COMMAND_EXECUTORS = {
       adoptPaths: options.adopt,
       strict: options.strict,
       fix: options.fix,
+      repositoryIndex: true,
     });
     return { result, exitCode: result.ok ? 0 : 1 };
   },
@@ -663,9 +672,33 @@ export const COMMAND_EXECUTORS = {
     exitCode: 0,
   }),
   update: async ({ target, packageRoot, packageVersion, options }) => {
-    const result = await runUpdate({ target, dryRun: options.dryRun, packageRoot, packageVersion });
+    const result = await runUpdate({ target, dryRun: options.dryRun, packageRoot, packageVersion, repositoryIndex: true });
     return { result, exitCode: result.conflicts.length === 0 ? 0 : 1 };
   },
+  "index-setup": async ({ target, packageRoot, options }) => ({
+    result: await runRepositoryIndexSetup({ target, packageRoot, options }),
+    exitCode: 0,
+  }),
+  "index-start": async ({ target, packageRoot, options }) => ({
+    result: await runRepositoryIndexStart({ target, packageRoot, options }),
+    exitCode: 0,
+  }),
+  "index-stop": async ({ target, packageRoot, options }) => ({
+    result: await runRepositoryIndexStop({ target, packageRoot, options }),
+    exitCode: 0,
+  }),
+  "index-status": async ({ target, packageRoot, options }) => ({
+    result: await runRepositoryIndexStatus({ target, packageRoot, options }),
+    exitCode: 0,
+  }),
+  "index-rebuild": async ({ target, packageRoot, options }) => ({
+    result: await runRepositoryIndexRebuild({ target, packageRoot, options }),
+    exitCode: 0,
+  }),
+  search: async ({ target, packageRoot, options, transport = "integration" }) => ({
+    result: await runSearch({ target, packageRoot, options, transport }),
+    exitCode: 0,
+  }),
 };
 
 export const EXECUTOR_EXCEPTIONS = Object.freeze([

package/src/core/command-input.js

@@ -8,6 +8,12 @@ function inputError(message) {
   return error;
 }
 
+function validateSearchCommandInput(command, options, help) {
+  if (command === "search" && !help && (typeof options.pattern !== "string" || options.pattern.length === 0)) {
+    throw inputError("search requires a pattern");
+  }
+}
+
 /**
  * Transport-neutral option defaults shared by the CLI parser and the
  * programmatic command runtime so every executor observes the same
@@ -22,6 +28,22 @@ export function defaultCommandInputValues() {
     strict: false,
     fix: false,
     adopt: [],
+    pattern: null,
+    globs: [],
+    types: [],
+    fixedStrings: false,
+    ignoreCase: false,
+    smartCase: false,
+    wordRegexp: false,
+    context: null,
+    beforeContext: null,
+    afterContext: null,
+    maxCount: null,
+    filesWithMatches: false,
+    stats: false,
+    assetPath: null,
+    binaryPath: null,
+    force: false,
     workType: null,
     surfaces: [],
     risks: [],
@@ -118,6 +140,7 @@ export function validateForgeLoopCommandInput({ command, input, help = false } =
   if (command === "task-create" && !options.taskId) {
     throw inputError("task-create requires --task");
   }
+  validateSearchCommandInput(command, options, help);
   if (options.executionProfile !== null && options.executionProfile !== undefined) {
     if (command !== "route") throw inputError(`executionProfile is not valid for ${command}`);
     if (!EXECUTION_PROFILE_REQUESTS.includes(options.executionProfile)) {

package/src/core/error-codes.js

@@ -11,6 +11,36 @@ import {
   E_VERIFICATION_ISOLATION_UNAVAILABLE,
 } from "./verification-execution.js";
 
+export const E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED = "E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED";
+export const E_REPOSITORY_INDEX_ENGINE_MISSING = "E_REPOSITORY_INDEX_ENGINE_MISSING";
+export const E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED = "E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED";
+export const E_REPOSITORY_INDEX_ENGINE_CHECKSUM_MISMATCH = "E_REPOSITORY_INDEX_ENGINE_CHECKSUM_MISMATCH";
+export const E_REPOSITORY_INDEX_ENGINE_BINARY_CHECKSUM_MISMATCH = "E_REPOSITORY_INDEX_ENGINE_BINARY_CHECKSUM_MISMATCH";
+export const E_REPOSITORY_INDEX_ENGINE_EXTRACTION_FAILED = "E_REPOSITORY_INDEX_ENGINE_EXTRACTION_FAILED";
+export const E_REPOSITORY_INDEX_ENGINE_VERSION_MISMATCH = "E_REPOSITORY_INDEX_ENGINE_VERSION_MISMATCH";
+export const E_REPOSITORY_INDEX_ENGINE_EXECUTION_FAILED = "E_REPOSITORY_INDEX_ENGINE_EXECUTION_FAILED";
+export const E_REPOSITORY_INDEX_OUTPUT_LIMIT = "E_REPOSITORY_INDEX_OUTPUT_LIMIT";
+export const E_REPOSITORY_INDEX_NOT_INITIALIZED = "E_REPOSITORY_INDEX_NOT_INITIALIZED";
+export const E_REPOSITORY_INDEX_INDEXING = "E_REPOSITORY_INDEX_INDEXING";
+export const E_REPOSITORY_INDEX_SERVER_START_FAILED = "E_REPOSITORY_INDEX_SERVER_START_FAILED";
+export const E_REPOSITORY_INDEX_SERVER_STOP_FAILED = "E_REPOSITORY_INDEX_SERVER_STOP_FAILED";
+export const E_REPOSITORY_INDEX_SERVER_UNHEALTHY = "E_REPOSITORY_INDEX_SERVER_UNHEALTHY";
+export const E_REPOSITORY_INDEX_SEARCH_FAILED = "E_REPOSITORY_INDEX_SEARCH_FAILED";
+export const E_REPOSITORY_INDEX_OUTPUT_INVALID = "E_REPOSITORY_INDEX_OUTPUT_INVALID";
+export const E_REPOSITORY_INDEX_REBUILD_FAILED = "E_REPOSITORY_INDEX_REBUILD_FAILED";
+export const E_REPOSITORY_INDEX_REQUEST_INVALID = "E_REPOSITORY_INDEX_REQUEST_INVALID";
+export const E_REPOSITORY_INDEX_LOCK_UNSAFE = "E_REPOSITORY_INDEX_LOCK_UNSAFE";
+export const E_PERSISTENT_TRANSPORT_FRAME_INVALID = "E_PERSISTENT_TRANSPORT_FRAME_INVALID";
+export const E_PERSISTENT_TRANSPORT_FRAME_TOO_LARGE = "E_PERSISTENT_TRANSPORT_FRAME_TOO_LARGE";
+export const E_PERSISTENT_TRANSPORT_HOST_STALE = "E_PERSISTENT_TRANSPORT_HOST_STALE";
+export const E_PERSISTENT_TRANSPORT_INVALID_REQUEST = "E_PERSISTENT_TRANSPORT_INVALID_REQUEST";
+export const E_PERSISTENT_TRANSPORT_INVALID_RESPONSE = "E_PERSISTENT_TRANSPORT_INVALID_RESPONSE";
+export const E_PERSISTENT_TRANSPORT_OWNERSHIP_UNVERIFIED = "E_PERSISTENT_TRANSPORT_OWNERSHIP_UNVERIFIED";
+export const E_PERSISTENT_TRANSPORT_PROTOCOL_MISMATCH = "E_PERSISTENT_TRANSPORT_PROTOCOL_MISMATCH";
+export const E_PERSISTENT_TRANSPORT_START_FAILED = "E_PERSISTENT_TRANSPORT_START_FAILED";
+export const E_PERSISTENT_TRANSPORT_TIMEOUT = "E_PERSISTENT_TRANSPORT_TIMEOUT";
+export const E_PERSISTENT_TRANSPORT_UNAVAILABLE = "E_PERSISTENT_TRANSPORT_UNAVAILABLE";
+
 export const E_TASK_REQUIRED = "E_TASK_REQUIRED";
 export const E_TASK_NOT_FOUND = "E_TASK_NOT_FOUND";
 export const E_TASK_ALREADY_EXISTS = "E_TASK_ALREADY_EXISTS";
@@ -373,6 +403,140 @@ const ADVISORY_CONTEXT_AND_HANDOFF_ERROR_METADATA = Object.freeze(Object.fromEnt
   })],
 ]));
 
+const REPOSITORY_INDEX_ERROR_METADATA = Object.freeze(Object.fromEntries([
+  [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_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_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_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_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_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_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_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_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_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_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_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_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_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_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_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.",
+  ]],
+].map(([code, [meaning, safeResolution]]) => [code, Object.freeze({
+  code,
+  category: "repository-index",
+  classification: "PUBLIC_STABLE",
+  meaning,
+  safeResolution,
+})])));
+
+const PERSISTENT_TRANSPORT_ERROR_METADATA = Object.freeze(Object.fromEntries([
+  [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.",
+  ]],
+].map(([code, [meaning, safeResolution]]) => [code, Object.freeze({
+  code,
+  category: "persistent-transport",
+  classification: "PUBLIC_STABLE",
+  meaning,
+  safeResolution,
+})])));
+
 /**
  * Public, stable ForgeLoop error and reason codes documented for users and harnesses.
  */
@@ -380,6 +544,8 @@ export const PUBLIC_ERROR_CODES = Object.freeze({
   ...EXTENSION_PUBLIC_ERROR_CODES,
   ...STRUCTURAL_QUALITY_ERROR_METADATA,
   ...ADVISORY_CONTEXT_AND_HANDOFF_ERROR_METADATA,
+  ...REPOSITORY_INDEX_ERROR_METADATA,
+  ...PERSISTENT_TRANSPORT_ERROR_METADATA,
   E_PREFLIGHT_NOT_READY: Object.freeze({
     code: "E_PREFLIGHT_NOT_READY",
     category: "preflight",
@@ -1259,6 +1425,35 @@ export const ALL_KNOWN_ERROR_CODES = Object.freeze(new Set([
   E_BASELINE_RECORD_DURING_ACTIVE_TASK,
   E_POLICY_INITIALIZATION_FAILED,
   E_INIT_KIT_CONFLICT,
+  E_REPOSITORY_INDEX_PLATFORM_UNSUPPORTED,
+  E_REPOSITORY_INDEX_ENGINE_MISSING,
+  E_REPOSITORY_INDEX_ENGINE_DOWNLOAD_FAILED,
+  E_REPOSITORY_INDEX_ENGINE_CHECKSUM_MISMATCH,
+  E_REPOSITORY_INDEX_ENGINE_BINARY_CHECKSUM_MISMATCH,
+  E_REPOSITORY_INDEX_ENGINE_EXTRACTION_FAILED,
+  E_REPOSITORY_INDEX_ENGINE_VERSION_MISMATCH,
+  E_REPOSITORY_INDEX_ENGINE_EXECUTION_FAILED,
+  E_REPOSITORY_INDEX_OUTPUT_LIMIT,
+  E_REPOSITORY_INDEX_NOT_INITIALIZED,
+  E_REPOSITORY_INDEX_INDEXING,
+  E_REPOSITORY_INDEX_SERVER_START_FAILED,
+  E_REPOSITORY_INDEX_SERVER_STOP_FAILED,
+  E_REPOSITORY_INDEX_SERVER_UNHEALTHY,
+  E_REPOSITORY_INDEX_SEARCH_FAILED,
+  E_REPOSITORY_INDEX_OUTPUT_INVALID,
+  E_REPOSITORY_INDEX_REBUILD_FAILED,
+  E_REPOSITORY_INDEX_REQUEST_INVALID,
+  E_REPOSITORY_INDEX_LOCK_UNSAFE,
+  E_PERSISTENT_TRANSPORT_FRAME_INVALID,
+  E_PERSISTENT_TRANSPORT_FRAME_TOO_LARGE,
+  E_PERSISTENT_TRANSPORT_HOST_STALE,
+  E_PERSISTENT_TRANSPORT_INVALID_REQUEST,
+  E_PERSISTENT_TRANSPORT_INVALID_RESPONSE,
+  E_PERSISTENT_TRANSPORT_OWNERSHIP_UNVERIFIED,
+  E_PERSISTENT_TRANSPORT_PROTOCOL_MISMATCH,
+  E_PERSISTENT_TRANSPORT_START_FAILED,
+  E_PERSISTENT_TRANSPORT_TIMEOUT,
+  E_PERSISTENT_TRANSPORT_UNAVAILABLE,
   E_ACTION_INVALID,
   E_ACTION_NOT_FOUND,
   E_ACTION_STATE_MISMATCH,