@cassiomc1/forgeloop 1.10.1 → 1.11.0

package/src/core/integration-resources.js

@@ -20,6 +20,7 @@ import { readVerificationScope } from "./verification-scope.js";
 import { resolveAttestationStatus } from "./attestation.js";
 import { buildExecutionProfileContext } from "./execution-profile-context.js";
 import { projectStructuralQualityStatus } from "./structural-quality/service.js";
+import { getRepositoryIndexStatus } from "../repository-index/status.js";
 
 /**
  * Canonical integration resource allowlist.
@@ -87,6 +88,7 @@ export const INTEGRATION_RESOURCE_DEFINITIONS = Object.freeze({
   "task/context": Object.freeze({ scope: "TASK", description: "Read-only profile-aware task context with bounded presentation policy." }),
   "task/evaluations": Object.freeze({ scope: "TASK", description: "Persisted trajectory evaluations for one task." }),
   "project/capability-policy": Object.freeze({ scope: "PROJECT", description: "Project capability policy, never host authority." }),
+  "repository/index-status": Object.freeze({ scope: "PROJECT", description: "Provider-neutral repository-index health and owned-server status." }),
 });
 
 function ownershipProjection(projection) {
@@ -103,7 +105,7 @@ function ownershipProjection(projection) {
   };
 }
 
-export async function readForgeLoopIntegrationResource(uri, {
+async function readForgeLoopIntegrationResourceCore(uri, {
   projectPath = ".",
   packageRoot = undefined,
   packageVersion = null,
@@ -288,3 +290,16 @@ export async function readForgeLoopIntegrationResource(uri, {
   const continuity = await runContinuity({ target: projectPath, packageRoot, taskId });
   return { uri, taskId, data: continuity };
 }
+
+export async function readForgeLoopIntegrationResource(uri, options = {}) {
+  if (uri === "repository/index-status") {
+    return {
+      uri,
+      data: await getRepositoryIndexStatus(options.projectPath ?? ".", {
+        packageRoot: options.packageRoot,
+        ...(options.repositoryIndexOptions ?? {}),
+      }),
+    };
+  }
+  return readForgeLoopIntegrationResourceCore(uri, options);
+}

package/src/core/protocol-info.js

@@ -47,6 +47,29 @@ export function protocolInfo({ packageVersion = null } = {}) {
         structuredCommandRuntime: true,
         canonicalResources: true,
       },
+      repositoryIndex: {
+        version: 1,
+        required: true,
+        providerNeutral: true,
+        implementation: "microsoft/tgrep",
+        engineVersion: "1.0.3",
+        engineManagedByForgeLoop: true,
+        commands: ["search", "index-setup", "index-start", "index-stop", "index-status", "index-rebuild"],
+        resource: "repository/index-status",
+        managedBinary: true,
+        path: ".forgeloop/repository-index/tgrep",
+        lifecycleStatePath: ".forgeloop/repository-index/engine-state.json",
+        noPathFallback: true,
+        supports: {
+          regex: true,
+          fixedStrings: true,
+          glob: true,
+          fileType: true,
+          context: true,
+          structuredOutput: true,
+          liveIndex: true,
+        },
+      },
       executionHistory: {
         version: 1,
         supported: true,

package/src/core/work-state.js

@@ -307,12 +307,21 @@ export async function mutateWorkState(target, { expectedRevision, packageRoot =
     throw error;
   }
   if (!(await getTaskTransaction(target))) {
-    return withTaskTransaction({
-      target,
-      taskId: taskId ?? "legacy-work-state",
-      lockTaskId: taskId ?? "legacy-work-state",
-      operation: "mutate-work-state",
-    }, async () => mutateWorkState(target, { expectedRevision, packageRoot, taskId, statePath }, updater));
+    try {
+      return await withTaskTransaction({
+        target,
+        taskId: taskId ?? "legacy-work-state",
+        lockTaskId: taskId ?? "legacy-work-state",
+        operation: "mutate-work-state",
+      }, async () => mutateWorkState(target, { expectedRevision, packageRoot, taskId, statePath }, updater));
+    } catch (error) {
+      if (error?.code === "E_TASK_LOCKED") {
+        const revisionError = new WorkStateError("Work state revision is being mutated concurrently");
+        revisionError.code = "E_STATE_REVISION_CONFLICT";
+        throw revisionError;
+      }
+      throw error;
+    }
   }
   const current = await readWorkState(target, { packageRoot, taskId, statePath });
   if (!current || (current.revision ?? 0) !== expectedRevision) {

package/src/integration.d.ts

@@ -19,6 +19,88 @@ export interface ForgeLoopCommandInput {
   commandArgv?: string[];
 }
 
+export interface RepositorySearchRequest {
+  pattern: string;
+  globs?: string[];
+  types?: string[];
+  fixedStrings?: boolean;
+  ignoreCase?: boolean;
+  smartCase?: boolean;
+  wordRegexp?: boolean;
+  context?: number | null;
+  beforeContext?: number | null;
+  afterContext?: number | null;
+  maxCount?: number | null;
+  filesWithMatches?: boolean;
+  stats?: boolean;
+  /** Explicit host-selected binary override; ForgeLoop never discovers PATH executables. */
+  binaryPath?: string;
+  /** Preloaded archive used by the managed-engine provisioning path. */
+  assetPath?: string;
+}
+
+export interface RepositorySearchSubmatch {
+  start: number;
+  end: number;
+  match: string | null;
+}
+
+export interface RepositorySearchMatch {
+  path: string;
+  line: number;
+  column: number | null;
+  offset: number | null;
+  text: string;
+  submatches: readonly RepositorySearchSubmatch[];
+}
+
+export interface RepositorySearchResult {
+  schemaVersion: 1;
+  query: RepositorySearchRequest & { globs: readonly string[]; types: readonly string[] };
+  repositoryIndex: { engine: string; engineVersion: string | null; indexed: boolean; server: boolean };
+  matches: readonly RepositorySearchMatch[];
+  contexts: readonly RepositorySearchMatch[];
+  files: readonly string[];
+  stats: Readonly<Record<string, number>>;
+  metrics: {
+    queryDurationMs: number;
+    nativeDurationMs: number;
+    matchCount: number;
+    matchedFileCount: number;
+    engine: string;
+    engineVersion: string | null;
+    serverUsed: boolean;
+    exitCode: number;
+    ignoredNativeEvents: number;
+    bytesSearched?: number;
+    matchedLines?: number;
+  };
+}
+
+export interface RepositoryIndexStatus {
+  schemaVersion: 1;
+  required: true;
+  engine: "tgrep";
+  engineVersion: string | null;
+  managedBinary: boolean;
+  overridden: boolean;
+  index: {
+    present: boolean;
+    complete: boolean;
+    files: number | null;
+    trigrams: number | null;
+    createdAt: number | null;
+    updatedAt: number | null;
+  };
+  policy: { maxFileSize: string | number; maxCpuPercent: number; watcherQueueCap: number; autoSaveMutations: number };
+  server: { running: boolean; owned: boolean; pid: number | null; port: number | null; watcher: string; indexing: string; files: number | null };
+  health: "READY" | "INDEXING" | "NOT_INITIALIZED" | "ENGINE_MISSING" | "ENGINE_INVALID" | "SERVER_DOWN" | "SERVER_UNHEALTHY" | "ERROR";
+  diagnostics: readonly { code: string; message: string }[];
+}
+
+export declare function repositorySearch(input: RepositorySearchRequest & { projectPath?: string }): Promise<RepositorySearchResult>;
+export declare function repositoryIndexStatus(input?: { projectPath?: string; binaryPath?: string; assetPath?: string }): Promise<RepositoryIndexStatus>;
+
 export interface ForgeLoopCommandEnvelope<T = unknown> {
   ok: boolean;
   command: string | null;
@@ -108,6 +190,14 @@ export interface ForgeLoopAdvisoryContextProvider {
 
 export type ForgeLoopAdvisoryContextProviderFactory = () => ForgeLoopAdvisoryContextProvider | Promise<ForgeLoopAdvisoryContextProvider>;
 
+/** Options for the optional, host-injected Ripwire advisory adapter. */
+export interface ForgeLoopRipwireProviderOptions {
+  /** Absolute path selected by the host; ForgeLoop does not discover it. */
+  executablePath: string;
+  /** Exact version string qualified by the host and checked lazily at recall time. */
+  expectedVersion: string;
+}
+
 export interface ForgeLoopNormalizedAdvisoryContextResult {
   provider: {
     id: string;
@@ -257,6 +347,14 @@ export declare function getForgeLoopCapabilities(input?: { packageVersion?: stri
 export declare function classifyForgeLoopInvocation(command: string, input?: ForgeLoopCommandInput): ForgeLoopInvocationClassification;
 export declare function readForgeLoopIntegrationResource(uri: string, input?: Record<string, unknown>): Promise<Record<string, unknown>>;
 export declare function resolveForgeLoopProjectRoot(projectPath?: string, input?: { cwd?: string }): Promise<string>;
+export declare function searchRepository(request: RepositorySearchRequest & { repoRoot: string }): Promise<RepositorySearchResult>;
+export declare function searchRepository(projectPath: string, request: RepositorySearchRequest): Promise<RepositorySearchResult>;
+export declare function getRepositoryIndexStatus(projectPath: string, options?: Record<string, unknown>): Promise<RepositoryIndexStatus>;
+export declare function setupRepositoryIndex(projectPath: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function startRepositoryIndexServer(projectPath: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function stopRepositoryIndexServer(projectPath: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function rebuildRepositoryIndex(projectPath: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function restartRepositoryIndexServer(projectPath: string, options?: Record<string, unknown>): Promise<Record<string, unknown>>;
 export declare function createForgeLoopContext(input?: Record<string, unknown>): ForgeLoopContext;
 export declare function recallAdvisoryContext(input: {
   target: string;
@@ -269,6 +367,9 @@ export declare function recallAdvisoryContext(input: {
   timeoutMs?: number;
   runtimeContext?: ForgeLoopContext | Record<string, unknown>;
 }): Promise<ForgeLoopNormalizedAdvisoryContextResult>;
+export declare function createRipwireAdvisoryContextProvider(
+  options: ForgeLoopRipwireProviderOptions,
+): ForgeLoopAdvisoryContextProvider;
 export declare const ADVISORY_CONTEXT_LIMITS: Readonly<Record<string, number>>;
 export declare const ADVISORY_CONTEXT_TRUST: Readonly<Record<string, unknown>>;
 export declare function normalizeAdvisoryRecallOptions(input?: Partial<ForgeLoopAdvisoryRecallOptions>): ForgeLoopAdvisoryRecallOptions;

package/src/integration.js

@@ -46,6 +46,27 @@ export {
 };
 
 export { createForgeLoopContext } from "./core/runtime-context.js";
+export { searchRepository } from "./repository-index/search.js";
+export { getRepositoryIndexStatus } from "./repository-index/status.js";
+export {
+  rebuildRepositoryIndex,
+  restartRepositoryIndexServer,
+  setupRepositoryIndex,
+  startRepositoryIndexServer,
+  stopRepositoryIndexServer,
+} from "./repository-index/server.js";
+
+/** Stable Integration API operation for provider-neutral repository search. */
+export async function repositorySearch({ projectPath = ".", ...request } = {}) {
+  const { searchRepository } = await import("./repository-index/search.js");
+  return searchRepository(projectPath, request);
+}
+
+/** Stable read-only Integration API projection for repository-index health. */
+export async function repositoryIndexStatus({ projectPath = ".", ...options } = {}) {
+  const { getRepositoryIndexStatus } = await import("./repository-index/status.js");
+  return getRepositoryIndexStatus(projectPath, options);
+}
 export {
   assertStructuralQualityProvider,
   createStructuralQualityProviderRegistry,
@@ -81,6 +102,7 @@ export {
   VERIFICATION_ISOLATION_MODES,
 } from "./core/verification-execution.js";
 export { recallAdvisoryContext } from "./core/advisory-context/service.js";
+export { createRipwireAdvisoryContextProvider } from "./adapters/ripwire/provider.js";
 export {
   ADVISORY_CONTEXT_LIMITS,
   ADVISORY_CONTEXT_TRUST,

package/src/persistent-transport/client.js

@@ -0,0 +1,293 @@
+import net from "node:net";
+import path from "node:path";
+import { readFile, realpath } from "node:fs/promises";
+
+import { getPackageRoot } from "../core/templates.js";
+import { acquirePersistentTransportStartupLock, cleanPersistentTransportState, getPersistentTransportStatus as getLifecycleStatus, inspectPersistentTransport, startPersistentSearchHost } from "./lifecycle.js";
+import { PERSISTENT_TRANSPORT_DEFAULTS, PERSISTENT_TRANSPORT_PROTOCOL_VERSION } from "./constants.js";
+import { encodeFrame, FrameDecoder, parseFrame } from "./framing.js";
+import { assertSearchParams, createRequest, projectSearchQuery, validateResponse } from "./protocol.js";
+import { PERSISTENT_TRANSPORT_ERROR_CODES, isPersistentTransportError, persistentTransportError } from "./errors.js";
+import { getPersistentTransportPaths } from "./paths.js";
+import { readPersistentTransportState } from "./state.js";
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+let forgeLoopVersionPromise;
+
+async function currentForgeLoopVersion() {
+  forgeLoopVersionPromise ??= readFile(path.join(getPackageRoot(), "package.json"), "utf8")
+    .then((raw) => JSON.parse(raw).version ?? null);
+  return forgeLoopVersionPromise;
+}
+
+function isConnectionFailure(error) {
+  return isPersistentTransportError(error)
+    && [PERSISTENT_TRANSPORT_ERROR_CODES.UNAVAILABLE, PERSISTENT_TRANSPORT_ERROR_CODES.TIMEOUT, PERSISTENT_TRANSPORT_ERROR_CODES.PROTOCOL_MISMATCH, PERSISTENT_TRANSPORT_ERROR_CODES.INVALID_RESPONSE].includes(error.code);
+}
+
+function remoteError(response) {
+  const error = persistentTransportError(response.error.code, response.error.message, {
+    expectedVersion: response.error.expectedVersion,
+    actualVersion: response.error.actualVersion,
+  });
+  error.remote = true;
+  return error;
+}
+
+function connect(endpoint, timeoutMs) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const socket = net.createConnection(endpoint);
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      socket.destroy();
+      reject(persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.TIMEOUT, "Timed out connecting to the persistent search host"));
+    }, timeoutMs);
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      fn(value);
+    };
+    socket.once("connect", () => {
+      socket.setNoDelay?.(true);
+      finish(resolve, socket);
+    });
+    socket.once("error", (cause) => finish(reject, persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.UNAVAILABLE, `Persistent search host is unavailable: ${cause.code ?? cause.message}`)));
+  });
+}
+
+function exchange(socket, request, timeoutMs, {
+  requestMaxFrameBytes = PERSISTENT_TRANSPORT_DEFAULTS.maxRequestFrameBytes,
+  responseMaxFrameBytes = PERSISTENT_TRANSPORT_DEFAULTS.maxResponseFrameBytes,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    const decoder = new FrameDecoder({ maxFrameBytes: responseMaxFrameBytes });
+    let settled = false;
+    const timer = setTimeout(() => finish(reject, persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.TIMEOUT, "Timed out waiting for the persistent search host")), timeoutMs);
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      socket.off("data", onData);
+      socket.off("error", onError);
+      socket.off("end", onEnd);
+      fn(value);
+    };
+    const onData = (chunk) => {
+      try {
+        for (const frame of decoder.push(chunk)) {
+          const response = validateResponse(parseFrame(frame), request.id);
+          finish(resolve, response);
+          return;
+        }
+      } catch (error) {
+        finish(reject, error.code ? error : persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.INVALID_RESPONSE, error.message));
+      }
+    };
+    const onError = (cause) => finish(reject, persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.UNAVAILABLE, `Persistent search host connection failed: ${cause.code ?? cause.message}`));
+    const onEnd = () => {
+      try { decoder.end(); } catch (error) { finish(reject, error); return; }
+      finish(reject, persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.UNAVAILABLE, "Persistent search host closed the connection"));
+    };
+    socket.on("data", onData);
+    socket.once("error", onError);
+    socket.once("end", onEnd);
+    try {
+      socket.write(encodeFrame(request, { maxFrameBytes: requestMaxFrameBytes }));
+    } catch (error) {
+      finish(reject, error);
+    }
+  });
+}
+
+async function openHost({
+  paths,
+  timeoutMs,
+  state,
+  requestMaxFrameBytes = PERSISTENT_TRANSPORT_DEFAULTS.maxRequestFrameBytes,
+  responseMaxFrameBytes = PERSISTENT_TRANSPORT_DEFAULTS.maxResponseFrameBytes,
+}) {
+  const socket = await connect(paths.endpoint, timeoutMs);
+  try {
+    const handshakeRequest = createRequest("handshake", { scopeId: paths.scopeId });
+    const handshake = await exchange(socket, handshakeRequest, timeoutMs, { requestMaxFrameBytes, responseMaxFrameBytes });
+    if (!handshake.ok) throw remoteError(handshake);
+    const expectedForgeLoopVersion = await currentForgeLoopVersion();
+    if (!handshake.result
+      || handshake.result.protocolVersion !== PERSISTENT_TRANSPORT_PROTOCOL_VERSION
+      || handshake.result.scopeId !== paths.scopeId
+      || handshake.result.forgeLoopVersion !== expectedForgeLoopVersion
+      || (state?.forgeLoopVersion && handshake.result.forgeLoopVersion !== state.forgeLoopVersion)) {
+      throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.PROTOCOL_MISMATCH, "Persistent search host handshake is incompatible", { expectedVersion: PERSISTENT_TRANSPORT_PROTOCOL_VERSION, actualVersion: handshake.result?.protocolVersion });
+    }
+    if (state?.nonce && handshake.result.nonce !== state.nonce) {
+      throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.OWNERSHIP_UNVERIFIED, "Persistent search host handshake ownership does not match its state");
+    }
+    return { socket, handshake: handshake.result };
+  } catch (error) {
+    socket.destroy();
+    throw error;
+  }
+}
+
+async function pingHost({ homeDirectory, timeoutMs, maxFrameBytes }) {
+  const paths = getPersistentTransportPaths({ homeDirectory });
+  const { state } = await readPersistentTransportState(paths.statePath);
+  if (!state) throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.UNAVAILABLE, "Persistent search host has not published its state");
+  const connection = await openHost({ paths, timeoutMs, state, responseMaxFrameBytes: maxFrameBytes });
+  try {
+    return connection.handshake;
+  } finally {
+    connection.socket.end();
+  }
+}
+
+export async function pingPersistentSearchHost({ homeDirectory = undefined, timeoutMs = 2_000 } = {}) {
+  const resolvedHome = homeDirectory ?? process.env.FORGELOOP_PERSISTENT_TRANSPORT_HOME ?? undefined;
+  return pingHost({
+    homeDirectory: resolvedHome,
+    timeoutMs,
+    maxFrameBytes: PERSISTENT_TRANSPORT_DEFAULTS.maxResponseFrameBytes,
+  });
+}
+
+function searchQuery(request) {
+  return projectSearchQuery(request);
+}
+
+async function requestSearch({ repositoryRoot, request, options, timeoutMs, maxFrameBytes }) {
+  const homeDirectory = options.homeDirectory;
+  const paths = getPersistentTransportPaths({ homeDirectory });
+  const { state } = await readPersistentTransportState(paths.statePath);
+  const params = assertSearchParams({ repository: repositoryRoot, query: searchQuery(request) });
+  const connection = await openHost({ paths, timeoutMs, state, responseMaxFrameBytes: maxFrameBytes });
+  try {
+    const response = await exchange(connection.socket, createRequest("repository.search", params), timeoutMs, {
+      responseMaxFrameBytes: maxFrameBytes,
+    });
+    if (!response.ok) throw remoteError(response);
+    return response.result;
+  } finally {
+    connection.socket.end();
+  }
+}
+
+async function ensureHost({ homeDirectory, idleTimeoutMs, startupTimeoutMs, env, recover = false }) {
+  const deadline = Date.now() + startupTimeoutMs;
+  let lock = null;
+  while (!lock) {
+    lock = await acquirePersistentTransportStartupLock({ homeDirectory, tryOnly: true });
+    if (lock) break;
+    if (Date.now() >= deadline) {
+      throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.START_FAILED, "Persistent search host startup coordination exceeded its bounded timeout");
+    }
+    await delay(Math.min(25, Math.max(1, deadline - Date.now())));
+  }
+  try {
+    let inspection = await inspectPersistentTransport({ homeDirectory });
+    if (inspection.status === "OWNERSHIP_UNVERIFIED") {
+      throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.OWNERSHIP_UNVERIFIED, "A process owns the persistent search endpoint but is not a verified ForgeLoop host");
+    }
+    if (inspection.status === "STALE") {
+      await cleanPersistentTransportState(inspection);
+      inspection = await inspectPersistentTransport({ homeDirectory });
+    }
+    if (inspection.status === "INCOMPATIBLE" || (recover && inspection.status === "READY")) {
+      await cleanPersistentTransportState(inspection);
+      inspection = await inspectPersistentTransport({ homeDirectory });
+    }
+    if (inspection.status === "READY") {
+      try {
+        await pingHost({ homeDirectory, timeoutMs: Math.min(startupTimeoutMs, 2_000), maxFrameBytes: PERSISTENT_TRANSPORT_DEFAULTS.maxResponseFrameBytes });
+        return inspection;
+      } catch (error) {
+        if (!recover && !isConnectionFailure(error)) throw error;
+        await cleanPersistentTransportState(inspection);
+      }
+    }
+    await startPersistentSearchHost({ homeDirectory, idleTimeoutMs, env });
+    const deadline = Date.now() + startupTimeoutMs;
+    while (Date.now() < deadline) {
+      try {
+        await pingHost({ homeDirectory, timeoutMs: Math.min(1_000, Math.max(100, deadline - Date.now())), maxFrameBytes: PERSISTENT_TRANSPORT_DEFAULTS.maxResponseFrameBytes });
+        return await inspectPersistentTransport({ homeDirectory });
+      } catch (error) {
+        if (!isConnectionFailure(error) && error.code !== PERSISTENT_TRANSPORT_ERROR_CODES.UNAVAILABLE) throw error;
+        await delay(25);
+      }
+    }
+    throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.START_FAILED, "Persistent search host did not become ready within the startup timeout");
+  } finally {
+    await lock.release();
+  }
+}
+
+const startupCoordinators = new Map();
+
+function coordinateEnsureHost(options) {
+  const key = getPersistentTransportPaths({ homeDirectory: options.homeDirectory }).root;
+  const active = startupCoordinators.get(key);
+  if (active) return active;
+  const pending = ensureHost(options);
+  startupCoordinators.set(key, pending);
+  const clear = () => {
+    if (startupCoordinators.get(key) === pending) startupCoordinators.delete(key);
+  };
+  pending.then(clear, clear);
+  return pending;
+}
+
+export async function searchViaPersistentTransport(repositoryRoot, request = {}, options = {}) {
+  const canonicalRoot = await realpath(repositoryRoot);
+  const homeDirectory = options.homeDirectory ?? process.env.FORGELOOP_PERSISTENT_TRANSPORT_HOME ?? undefined;
+  const transportOptions = {
+    homeDirectory,
+    idleTimeoutMs: options.idleTimeoutMs ?? PERSISTENT_TRANSPORT_DEFAULTS.idleTimeoutMs,
+    startupTimeoutMs: options.startupTimeoutMs ?? PERSISTENT_TRANSPORT_DEFAULTS.startupTimeoutMs,
+    requestTimeoutMs: options.requestTimeoutMs ?? PERSISTENT_TRANSPORT_DEFAULTS.requestTimeoutMs,
+    maxFrameBytes: options.maxResponseFrameBytes ?? PERSISTENT_TRANSPORT_DEFAULTS.maxResponseFrameBytes,
+    env: options.env ?? {},
+  };
+  let lastError;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return await requestSearch({ repositoryRoot: canonicalRoot, request, options: transportOptions, timeoutMs: transportOptions.requestTimeoutMs, maxFrameBytes: transportOptions.maxFrameBytes });
+    } catch (error) {
+      lastError = error;
+      if (error.remote || !isConnectionFailure(error)) throw error;
+      await coordinateEnsureHost({ ...transportOptions, recover: attempt === 1 });
+    }
+  }
+  throw lastError ?? persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.UNAVAILABLE, "Persistent search host is unavailable");
+}
+
+export async function shutdownPersistentSearchHost({ homeDirectory = undefined, timeoutMs = 2_000 } = {}) {
+  const resolvedHome = homeDirectory ?? process.env.FORGELOOP_PERSISTENT_TRANSPORT_HOME ?? undefined;
+  const inspection = await inspectPersistentTransport({ homeDirectory: resolvedHome });
+  if (inspection.status === "NOT_RUNNING") return { status: "NOT_RUNNING" };
+  if (!inspection.owned) throw persistentTransportError(PERSISTENT_TRANSPORT_ERROR_CODES.OWNERSHIP_UNVERIFIED, "Persistent search host ownership could not be verified");
+  const paths = getPersistentTransportPaths({ homeDirectory: resolvedHome });
+  const connection = await openHost({ paths, timeoutMs, state: inspection.state });
+  try {
+    const response = await exchange(connection.socket, createRequest("transport.shutdown", { nonce: inspection.state.nonce }), timeoutMs);
+    if (!response.ok) throw remoteError(response);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const status = await getLifecycleStatus({ homeDirectory: resolvedHome });
+      if (status.status === "NOT_RUNNING" || status.status === "STALE") break;
+      await delay(25);
+    }
+    return response.result;
+  } finally {
+    connection.socket.end();
+  }
+}
+
+export async function getPersistentTransportStatus(options = {}) {
+  return getLifecycleStatus(options);
+}

package/src/persistent-transport/constants.js

@@ -0,0 +1,24 @@
+import os from "node:os";
+import path from "node:path";
+
+export const PERSISTENT_TRANSPORT_PROTOCOL_VERSION = 1;
+export const PERSISTENT_TRANSPORT_SCHEMA_VERSION = 1;
+export const PERSISTENT_TRANSPORT_DEFAULTS = Object.freeze({
+  startupTimeoutMs: 15_000,
+  requestTimeoutMs: 120_000,
+  idleTimeoutMs: 10 * 60 * 1_000,
+  maxRequestFrameBytes: 1 * 1024 * 1024,
+  maxResponseFrameBytes: 16 * 1024 * 1024,
+  maxPatternChars: 4_096,
+});
+
+export const PERSISTENT_TRANSPORT_METHODS = Object.freeze([
+  "handshake",
+  "repository.search",
+  "transport.status",
+  "transport.shutdown",
+]);
+
+export function getPersistentTransportRoot({ homeDirectory = os.homedir() } = {}) {
+  return path.join(homeDirectory, ".forgeloop", "persistent-search");
+}

package/src/persistent-transport/errors.js

@@ -0,0 +1,38 @@
+import {
+  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,
+} from "../core/error-codes.js";
+
+export const PERSISTENT_TRANSPORT_ERROR_CODES = Object.freeze({
+  FRAME_INVALID: E_PERSISTENT_TRANSPORT_FRAME_INVALID,
+  FRAME_TOO_LARGE: E_PERSISTENT_TRANSPORT_FRAME_TOO_LARGE,
+  HOST_STALE: E_PERSISTENT_TRANSPORT_HOST_STALE,
+  INVALID_REQUEST: E_PERSISTENT_TRANSPORT_INVALID_REQUEST,
+  INVALID_RESPONSE: E_PERSISTENT_TRANSPORT_INVALID_RESPONSE,
+  OWNERSHIP_UNVERIFIED: E_PERSISTENT_TRANSPORT_OWNERSHIP_UNVERIFIED,
+  PROTOCOL_MISMATCH: E_PERSISTENT_TRANSPORT_PROTOCOL_MISMATCH,
+  START_FAILED: E_PERSISTENT_TRANSPORT_START_FAILED,
+  TIMEOUT: E_PERSISTENT_TRANSPORT_TIMEOUT,
+  UNAVAILABLE: E_PERSISTENT_TRANSPORT_UNAVAILABLE,
+});
+
+export function persistentTransportError(code, message, details = {}) {
+  const error = new Error(message);
+  error.code = code;
+  for (const [key, value] of Object.entries(details)) {
+    if (value !== undefined) error[key] = value;
+  }
+  return error;
+}
+
+export function isPersistentTransportError(error) {
+  return typeof error?.code === "string" && error.code.startsWith("E_PERSISTENT_TRANSPORT_");
+}