@moretea-labs/forge 1.5.1 → 1.7.0

package/src/cli/repository/session-cache.ts

@@ -49,6 +49,7 @@ export interface SessionCacheSnapshot {
   metrics: SessionCacheMetrics;
   fileCount: number;
   searchCount: number;
+  structuralCount: number;
 }
 
 function shaText(value: string): string {
@@ -101,9 +102,9 @@ function rangeKey(path: string, start: number, end: number): string {
 export class RepositorySessionCache {
   private identity: SessionIdentity;
   private readonly repoRoot: string;
-  private readonly fileSha = new Map<string, string>();
   private readonly ranges = new Map<string, FileRangeCacheEntry>();
   private readonly searches = new Map<string, SearchCacheEntry>();
+  private readonly structural = new Map<string, { at: number; value: unknown }>();
   private readonly gitSnapshots = new Map<string, { at: number; value: unknown }>();
   private readonly checks = new Map<string, unknown>();
   private runtimeGeneration?: string;
@@ -141,6 +142,7 @@ export class RepositorySessionCache {
       metrics: this.getMetrics(),
       fileCount: this.ranges.size,
       searchCount: this.searches.size,
+      structuralCount: this.structural.size,
     };
   }
 
@@ -148,6 +150,10 @@ export class RepositorySessionCache {
     return { ...this.identity };
   }
 
+  repositoryRootPath(): string {
+    return this.repoRoot;
+  }
+
   refreshIdentity(next: SessionIdentity): void {
     const prev = this.identity;
     this.identity = next;
@@ -178,16 +184,12 @@ export class RepositorySessionCache {
   }
 
   getFileSha(relativePath: string): string | null {
-    const cached = this.fileSha.get(relativePath);
-    if (cached) {
-      this.metrics.cacheHit += 1;
-      return cached;
-    }
-    const absolute = join(this.repoRoot, relativePath);
-    const sha = fileShaOf(absolute);
-    if (sha) this.fileSha.set(relativePath, sha);
-    this.metrics.cacheMiss += 1;
-    return sha;
+    // Range reuse is correctness-sensitive: Git identity is intentionally sampled
+    // with a short TTL, so it can lag an edit by a few seconds. Hash the current
+    // file bytes before serving a cached range instead of trusting an older
+    // session-level SHA. Warm filesystem hashing is sub-millisecond for normal
+    // source files and still preserves the expensive range/materialization reuse.
+    return fileShaOf(join(this.repoRoot, relativePath));
   }
 
   /**
@@ -213,15 +215,16 @@ export class RepositorySessionCache {
         entry.path === relativePath
         && entry.fileSha === sha
         && entry.startLine <= startLine
-        && entry.endLine >= endLine
+        && (entry.endLine >= endLine || entry.endLine >= entry.totalLines)
       ) {
         this.metrics.cacheHit += 1;
         this.metrics.bytesAvoided += Math.max(0, entry.bytes);
+        const resolvedEndLine = Math.min(endLine, entry.totalLines);
         return {
           ...entry,
           startLine,
-          endLine,
-          content: sliceNumberedContent(entry.content, entry.startLine, startLine, endLine),
+          endLine: resolvedEndLine,
+          content: sliceNumberedContent(entry.content, entry.startLine, startLine, resolvedEndLine),
         };
       }
     }
@@ -230,7 +233,6 @@ export class RepositorySessionCache {
   }
 
   putRange(entry: FileRangeCacheEntry): void {
-    this.fileSha.set(entry.path, entry.fileSha);
     this.ranges.set(rangeKey(entry.path, entry.startLine, entry.endLine), entry);
   }
 
@@ -251,6 +253,33 @@ export class RepositorySessionCache {
     this.searches.set(key, entry);
   }
 
+  getStructural(key: string, ttlMs = 30_000): unknown | null {
+    const scopedKey = `${this.identity.head}|${this.identity.workingTreeFingerprint}|${key}`;
+    const hit = this.structural.get(scopedKey);
+    if (hit && Date.now() - hit.at <= ttlMs) {
+      this.metrics.cacheHit += 1;
+      this.metrics.scanAvoided += 1;
+      return hit.value;
+    }
+    if (hit) this.structural.delete(scopedKey);
+    this.metrics.cacheMiss += 1;
+    return null;
+  }
+
+  /** Inspect structural reuse eligibility without changing request metrics. */
+  peekStructural(key: string, ttlMs = 30_000): unknown | null {
+    const scopedKey = `${this.identity.head}|${this.identity.workingTreeFingerprint}|${key}`;
+    const hit = this.structural.get(scopedKey);
+    if (hit && Date.now() - hit.at <= ttlMs) return hit.value;
+    if (hit) this.structural.delete(scopedKey);
+    return null;
+  }
+
+  putStructural(key: string, value: unknown): void {
+    const scopedKey = `${this.identity.head}|${this.identity.workingTreeFingerprint}|${key}`;
+    this.structural.set(scopedKey, { at: Date.now(), value });
+  }
+
   getGitSnapshot(): unknown | null {
     const key = `${this.identity.head}|${this.identity.workingTreeFingerprint}`;
     const hit = this.gitSnapshots.get(key);
@@ -284,7 +313,6 @@ export class RepositorySessionCache {
 
   /** Precise invalidation when one file changes. */
   invalidateFile(relativePath: string): void {
-    this.fileSha.delete(relativePath);
     for (const key of [...this.ranges.keys()]) {
       if (key.startsWith(`${relativePath}:`)) this.ranges.delete(key);
     }
@@ -294,9 +322,9 @@ export class RepositorySessionCache {
   }
 
   invalidateCheckout(): void {
-    this.fileSha.clear();
     this.ranges.clear();
     this.searches.clear();
+    this.structural.clear();
     this.gitSnapshots.clear();
     this.checks.clear();
     this.metrics.invalidations += 1;
@@ -304,6 +332,7 @@ export class RepositorySessionCache {
 
   invalidateHeadRelated(): void {
     this.searches.clear();
+    this.structural.clear();
     this.gitSnapshots.clear();
     this.checks.clear();
     this.metrics.invalidations += 1;
@@ -311,6 +340,7 @@ export class RepositorySessionCache {
 
   invalidateWorkingTree(): void {
     this.searches.clear();
+    this.structural.clear();
     this.gitSnapshots.clear();
     this.checks.clear();
     this.metrics.invalidations += 1;
@@ -406,6 +436,17 @@ export function pruneSessionCaches(nowMs = Date.now()): number {
 }
 
 /** Called by MCP transport close/eviction so read caches do not outlive a session. */
+export function invalidateSessionCachesForRepository(repoRoot: string): number {
+  const root = resolve(repoRoot);
+  let invalidated = 0;
+  for (const cache of globalSessions.values()) {
+    if (cache.repositoryRootPath() !== root) continue;
+    cache.invalidateWorkingTree();
+    invalidated += 1;
+  }
+  return invalidated;
+}
+
 export function clearSessionCachesForSession(sessionId: string): number {
   let removed = 0;
   for (const [key, cache] of globalSessions) {

package/src/cli/v81-entry.ts

@@ -1,11 +1,8 @@
 import { buildProgram } from './index';
-import { buildRepositoryCommand } from './commands/repository';
 import { CLI_VERSION } from './commands/status';
 
 export function buildV81Program() {
-  const program = buildProgram();
-  program.addCommand(buildRepositoryCommand());
-  return program;
+  return buildProgram();
 }
 
 export async function runV81Cli(argv: string[] = process.argv): Promise<void> {

package/src/effects/fs-transaction.ts

@@ -234,6 +234,26 @@ export function atomicWriteFile(
   });
 }
 
+/** Durable replacement for transaction metadata and rollback restores. Unlike
+ * atomicWriteFile, this intentionally does not create another recovery backup. */
+function replaceFileDurably(repoRoot: string, path: string, content: string, mode?: number): void {
+  const target = resolveInsideRepo(repoRoot, path);
+  if (!target.ok || !target.path) throw new Error(target.error ?? "invalid path");
+  const parentError = ensureParent(repoRoot, path);
+  if (parentError) throw new Error(parentError);
+  const targetPath = target.path;
+  withTargetLock(targetPath, () => {
+    const tempPath = resolve(dirname(targetPath), `.${basename(targetPath)}.${process.pid}.${Date.now()}.tmp`);
+    try {
+      writeFileDurably(tempPath, content, mode);
+      renameSync(tempPath, targetPath);
+      fsyncDirectory(dirname(targetPath));
+    } finally {
+      rmSync(tempPath, { force: true });
+    }
+  });
+}
+
 export function applyMkdirOperation(repoRoot: string, operation: MkdirOperation, dryRun = false): ApplyOperationResult {
   const target = resolveInsideRepo(repoRoot, operation.path);
   if (!target.ok || !target.path) return failure(operation, target.error ?? "invalid path");
@@ -311,12 +331,17 @@ export function applyAppendManagedBlockOperation(
   }
 }
 
-function writeTransactionManifest(plan: AdoptionPlan, transactionDir: string, results: readonly ApplyOperationResult[]): string {
+function writeTransactionManifest(
+  plan: AdoptionPlan,
+  transactionDir: string,
+  createdAt: string,
+  results: readonly ApplyOperationResult[],
+): string {
   const manifestPath = `${transactionDir}/manifest.json`;
   const manifest: FsTransactionManifest = {
     protocol: 1,
     command: "adopt",
-    createdAt: new Date().toISOString(),
+    createdAt,
     repoRoot: plan.repoRoot,
     mode: plan.mode,
     operations: results.map((result) => {
@@ -336,7 +361,7 @@ function writeTransactionManifest(plan: AdoptionPlan, transactionDir: string, re
       command: `forge adopt rollback --transaction ${manifestPath}`,
     },
   };
-  atomicWriteFile(plan.repoRoot, manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o600 });
+  replaceFileDurably(plan.repoRoot, manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, 0o600);
   return manifestPath;
 }
 
@@ -350,21 +375,64 @@ export function applyAdoptionPlan(plan: AdoptionPlan, dryRun = false): ApplyAdop
     };
   }
 
-  const transactionDir = dryRun ? undefined : transactionDirFor();
-  const results = plan.operations.map((operation) => {
-    switch (operation.kind) {
-      case "mkdir":
-        return applyMkdirOperation(plan.repoRoot, operation, dryRun);
-      case "writeFile":
-        return applyWriteFileOperation(plan.repoRoot, operation, dryRun, transactionDir);
-      case "appendManagedBlock":
-        return applyAppendManagedBlockOperation(plan.repoRoot, operation, dryRun, transactionDir);
-      default:
-        return failure(operation, `unsupported operation kind: ${operation.kind}`);
+  if (dryRun) {
+    const results = plan.operations.map((operation) => {
+      switch (operation.kind) {
+        case "mkdir": return applyMkdirOperation(plan.repoRoot, operation, true);
+        case "writeFile": return applyWriteFileOperation(plan.repoRoot, operation, true);
+        case "appendManagedBlock": return applyAppendManagedBlockOperation(plan.repoRoot, operation, true);
+        default: return failure(operation, `unsupported operation kind: ${operation.kind}`);
+      }
+    });
+    return { ok: results.every((result) => result.status !== "failed"), dryRun: true, results };
+  }
+
+  const transactionDir = transactionDirFor();
+  const createdAt = new Date().toISOString();
+  const results: ApplyOperationResult[] = [];
+  let transactionManifestPath: string;
+  try {
+    // Establish recovery evidence before the first adoption operation mutates
+    // repository state. Each completed/failed operation is checkpointed below.
+    transactionManifestPath = writeTransactionManifest(plan, transactionDir, createdAt, results);
+  } catch (error) {
+    return {
+      ok: false,
+      dryRun: false,
+      results: [{
+        id: "transaction-manifest",
+        kind: "runCheck",
+        status: "failed",
+        error: `failed to initialize transaction manifest: ${errorMessage(error)}`,
+      }],
+    };
+  }
+
+  for (const operation of plan.operations) {
+    const result = (() => {
+      switch (operation.kind) {
+        case "mkdir": return applyMkdirOperation(plan.repoRoot, operation, false);
+        case "writeFile": return applyWriteFileOperation(plan.repoRoot, operation, false, transactionDir);
+        case "appendManagedBlock": return applyAppendManagedBlockOperation(plan.repoRoot, operation, false, transactionDir);
+        default: return failure(operation, `unsupported operation kind: ${operation.kind}`);
+      }
+    })();
+    results.push(result);
+    try {
+      writeTransactionManifest(plan, transactionDir, createdAt, results);
+    } catch (error) {
+      results.push({
+        id: "transaction-manifest",
+        kind: "runCheck",
+        status: "failed",
+        error: `failed to checkpoint transaction manifest: ${errorMessage(error)}`,
+      });
+      break;
     }
-  });
+    if (result.status === "failed") break;
+  }
+
   const ok = results.every((result) => result.status !== "failed");
-  const transactionManifestPath = !dryRun && ok && transactionDir ? writeTransactionManifest(plan, transactionDir, results) : undefined;
 
   return {
     ok,
@@ -413,7 +481,7 @@ function rollbackFileOperation(repoRoot: string, operation: FsTransactionManifes
           return rollbackFailed(operation, "restore_backup", "current file hash differs from transaction content hash");
         }
       }
-      atomicWriteFile(repoRoot, operation.path, readFileSync(backup.path, "utf-8"));
+      replaceFileDurably(repoRoot, operation.path, readFileSync(backup.path, "utf-8"));
       return { id: operation.id, kind: operation.kind, path: operation.path, status: "rolled_back", action: "restore_backup" };
     } catch (error) {
       return rollbackFailed(operation, "restore_backup", errorMessage(error));

package/src/runtime/context/codegraph-read-provider.ts

@@ -1,7 +1,8 @@
-import { spawnSync } from 'child_process';
+import { spawn, spawnSync, type ChildProcessWithoutNullStreams } from 'child_process';
 import { accessSync, constants, existsSync } from 'fs';
 import { createRequire } from 'module';
 import { dirname, join, resolve } from 'path';
+import { createInterface, type Interface as ReadlineInterface } from 'readline';
 import { fileURLToPath } from 'url';
 
 const require = createRequire(import.meta.url);
@@ -10,6 +11,7 @@ const MAX_REQUEST_BYTES = 64 * 1024;
 const MAX_RESPONSE_BYTES = 1024 * 1024;
 const MAX_STDERR_CHARS = 8_000;
 const DEFAULT_TIMEOUT_MS = 15_000;
+const PERSISTENT_SIDECAR_IDLE_MS = 30_000;
 const ALLOWED_OPERATIONS = new Set<CodeGraphReadOperation>(['status', 'search', 'context', 'impact', 'file_dependencies']);
 
 export type CodeGraphReadOperation = 'status' | 'search' | 'context' | 'impact' | 'file_dependencies';
@@ -132,7 +134,8 @@ export function resolveCodeGraphBundledRuntime(options: { runtimeRoot?: string }
 } {
   const target = `${process.platform}-${process.arch}`;
   const platformPackage = `@colbymchenry/codegraph-${target}`;
-  const runtimeRoot = options.runtimeRoot ?? dirname(process.execPath);
+  const configuredReleaseRoot = process.env.FORGE_RELEASE_PATH?.trim();
+  const runtimeRoot = options.runtimeRoot ?? (configuredReleaseRoot ? resolve(configuredReleaseRoot) : dirname(process.execPath));
   const releaseNode = join(runtimeRoot, 'codegraph-node');
   const releaseSidecar = join(runtimeRoot, 'codegraph-sidecar.cjs');
   const releaseLibrary = join(runtimeRoot, 'codegraph-lib', 'dist', 'index.js');
@@ -345,3 +348,231 @@ export function queryCodeGraphReadProvider(
     },
   };
 }
+
+interface PersistentCodeGraphSession {
+  repoRoot: string;
+  runtimeKey: string;
+  child: ChildProcessWithoutNullStreams;
+  reader: ReadlineInterface;
+  lines: AsyncIterator<string>;
+  stderr: string;
+  closed: boolean;
+  idleTimer?: NodeJS.Timeout;
+  queue: Promise<void>;
+}
+
+const persistentSessions = new Map<string, PersistentCodeGraphSession>();
+let persistentSessionSpawns = 0;
+let persistentSessionReuses = 0;
+let persistentSessionRequests = 0;
+
+function persistentRuntimeKey(runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>): string {
+  return `${runtime.nodeExecutable}\u0000${runtime.sidecarPath}\u0000${runtime.libraryPath}`;
+}
+
+function closePersistentSessionNow(session: PersistentCodeGraphSession): void {
+  if (session.closed) return;
+  session.closed = true;
+  if (session.idleTimer) clearTimeout(session.idleTimer);
+  if (persistentSessions.get(session.repoRoot) === session) persistentSessions.delete(session.repoRoot);
+  try { session.reader.close(); } catch {}
+  try { session.child.stdin.end(); } catch {}
+  try { session.child.kill(); } catch {}
+}
+
+function schedulePersistentSessionIdle(session: PersistentCodeGraphSession): void {
+  if (session.idleTimer) clearTimeout(session.idleTimer);
+  const timer = setTimeout(() => closePersistentSessionNow(session), PERSISTENT_SIDECAR_IDLE_MS);
+  timer.unref();
+  session.idleTimer = timer;
+}
+
+function createPersistentSession(
+  repoRoot: string,
+  runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>,
+): PersistentCodeGraphSession {
+  const child = spawn(runtime.nodeExecutable, [runtime.sidecarPath], {
+    cwd: repoRoot,
+    env: { ...minimalEnvironment(runtime), FORGE_CODEGRAPH_PERSISTENT: '1' },
+    stdio: ['pipe', 'pipe', 'pipe'],
+    windowsHide: true,
+    shell: false,
+  });
+  child.unref();
+  const reader = createInterface({ input: child.stdout, crlfDelay: Infinity });
+  const session: PersistentCodeGraphSession = {
+    repoRoot,
+    runtimeKey: persistentRuntimeKey(runtime),
+    child,
+    reader,
+    lines: reader[Symbol.asyncIterator](),
+    stderr: '',
+    closed: false,
+    queue: Promise.resolve(),
+  };
+  child.stderr.on('data', (chunk: Buffer) => {
+    if (session.stderr.length >= MAX_STDERR_CHARS) return;
+    session.stderr += chunk.toString('utf8').slice(0, MAX_STDERR_CHARS - session.stderr.length);
+  });
+  child.on('error', () => closePersistentSessionNow(session));
+  child.on('close', () => {
+    session.closed = true;
+    if (session.idleTimer) clearTimeout(session.idleTimer);
+    if (persistentSessions.get(repoRoot) === session) persistentSessions.delete(repoRoot);
+  });
+  persistentSessions.set(repoRoot, session);
+  persistentSessionSpawns += 1;
+  return session;
+}
+
+function getPersistentSession(
+  repoRoot: string,
+  runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>,
+): PersistentCodeGraphSession {
+  const key = persistentRuntimeKey(runtime);
+  const current = persistentSessions.get(repoRoot);
+  if (current && !current.closed && current.runtimeKey === key) {
+    if (current.idleTimer) clearTimeout(current.idleTimer);
+    current.idleTimer = undefined;
+    persistentSessionReuses += 1;
+    return current;
+  }
+  if (current) closePersistentSessionNow(current);
+  return createPersistentSession(repoRoot, runtime);
+}
+
+async function serializedPersistentRequest<T>(session: PersistentCodeGraphSession, operation: () => Promise<T>): Promise<T> {
+  const previous = session.queue;
+  let release!: () => void;
+  session.queue = new Promise<void>((resolveQueue) => { release = resolveQueue; });
+  await previous.catch(() => undefined);
+  try {
+    return await operation();
+  } finally {
+    release();
+  }
+}
+
+async function nextPersistentLine(session: PersistentCodeGraphSession, timeoutMs: number): Promise<string> {
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    const timeout = new Promise<never>((_, reject) => {
+      timer = setTimeout(() => reject(new Error('CODEGRAPH_TIMEOUT')), timeoutMs);
+      timer.unref();
+    });
+    const next = await Promise.race([session.lines.next(), timeout]);
+    if (next.done || typeof next.value !== 'string') {
+      throw new Error(session.stderr || 'CODEGRAPH_SIDECAR_CLOSED');
+    }
+    return next.value;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+export async function closeCodeGraphReadProviderSessions(): Promise<void> {
+  const sessions = [...persistentSessions.values()];
+  persistentSessions.clear();
+  for (const session of sessions) closePersistentSessionNow(session);
+}
+
+export async function clearCodeGraphReadProviderSessionsForTest(): Promise<void> {
+  await closeCodeGraphReadProviderSessions();
+  persistentSessionSpawns = 0;
+  persistentSessionReuses = 0;
+  persistentSessionRequests = 0;
+}
+
+export function codeGraphReadProviderSessionSnapshotForTest(): {
+  active: number;
+  spawns: number;
+  reuses: number;
+  requests: number;
+} {
+  return {
+    active: persistentSessions.size,
+    spawns: persistentSessionSpawns,
+    reuses: persistentSessionReuses,
+    requests: persistentSessionRequests,
+  };
+}
+
+/** Async sidecar path used by the first broad Context Plane fan-in. */
+export async function queryCodeGraphReadProviderAsync(
+  repoRoot: string,
+  request: CodeGraphReadRequest,
+  options: { timeoutMs?: number } = {},
+): Promise<CodeGraphReadProviderResponse> {
+  const startedAt = performance.now();
+  if (!ALLOWED_OPERATIONS.has(request.operation)) {
+    return errorResponse(request.operation, 'CODEGRAPH_OPERATION_NOT_ALLOWED', `Unsupported read operation: ${String(request.operation)}`, performance.now() - startedAt);
+  }
+  let runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>;
+  try { runtime = resolveCodeGraphBundledRuntime(); }
+  catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return errorResponse(request.operation, message.split(':', 1)[0] || 'CODEGRAPH_RUNTIME_UNAVAILABLE', message, performance.now() - startedAt);
+  }
+  const resolvedRepoRoot = resolve(repoRoot);
+  const input = JSON.stringify({
+    schemaVersion: SCHEMA_VERSION,
+    operation: request.operation,
+    projectRoot: resolvedRepoRoot,
+    ...(typeof request.query === 'string' ? { query: request.query.slice(0, 2_000) } : {}),
+    ...(typeof request.nodeId === 'string' ? { nodeId: request.nodeId.slice(0, 1_000) } : {}),
+    ...(typeof request.filePath === 'string' ? { filePath: request.filePath.slice(0, 2_000) } : {}),
+    limit: boundedInteger(request.limit, 12, 1, 40),
+    maxNodes: boundedInteger(request.maxNodes, 40, 1, 80),
+    maxDepth: boundedInteger(request.maxDepth, 2, 1, 5),
+  });
+  if (Buffer.byteLength(input) > MAX_REQUEST_BYTES) {
+    return errorResponse(request.operation, 'CODEGRAPH_REQUEST_TOO_LARGE', 'CodeGraph request exceeded the bounded input limit.', performance.now() - startedAt);
+  }
+
+  let session = getPersistentSession(resolvedRepoRoot, runtime);
+  return await serializedPersistentRequest(session, async () => {
+    if (session.closed) session = getPersistentSession(resolvedRepoRoot, runtime);
+    const processStartedAt = performance.now();
+    persistentSessionRequests += 1;
+    try {
+      await new Promise<void>((resolveWrite, rejectWrite) => {
+        session.child.stdin.write(`${input}\n`, (error) => error ? rejectWrite(error) : resolveWrite());
+      });
+      const raw = await nextPersistentLine(
+        session,
+        boundedInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 1_000, 60_000),
+      );
+      if (Buffer.byteLength(raw) > MAX_RESPONSE_BYTES) {
+        closePersistentSessionNow(session);
+        return errorResponse(request.operation, 'CODEGRAPH_RESPONSE_TOO_LARGE', 'CodeGraph response exceeded the bounded output limit.', performance.now() - startedAt);
+      }
+      const parsed = parseSidecarResponse(raw);
+      if (!parsed.ok) {
+        schedulePersistentSessionIdle(session);
+        return errorResponse(request.operation, parsed.error.code, parsed.error.message, performance.now() - startedAt);
+      }
+      const metadata = filterGitIgnoredCodeGraphChanges(resolvedRepoRoot, parsed.metadata);
+      schedulePersistentSessionIdle(session);
+      return {
+        schemaVersion: 1,
+        provider: 'codegraph',
+        operation: request.operation,
+        ok: metadata.initialized,
+        status: providerStatus(metadata),
+        metadata,
+        result: parsed.result,
+        timingsMs: {
+          total: Math.round((performance.now() - startedAt) * 100) / 100,
+          process: Math.round((performance.now() - processStartedAt) * 100) / 100,
+          ...(typeof parsed.timingsMs?.open === 'number' ? { open: parsed.timingsMs.open } : {}),
+          ...(typeof parsed.timingsMs?.query === 'number' ? { query: parsed.timingsMs.query } : {}),
+        },
+      };
+    } catch (error) {
+      closePersistentSessionNow(session);
+      const message = error instanceof Error ? error.message : String(error);
+      const code = message === 'CODEGRAPH_TIMEOUT' ? 'CODEGRAPH_TIMEOUT' : 'CODEGRAPH_SIDECAR_FAILED';
+      return errorResponse(request.operation, code, message, performance.now() - startedAt);
+    }
+  });
+}