@moretea-labs/forge 1.5.0-rc.1

package/src/runtime/assistant/types.ts

@@ -0,0 +1,135 @@
+import type { ExecutionJob, ExecutionJobOrigin } from '../execution/jobs/types';
+
+export type AssistantIntentMode = 'plan_only' | 'plan_then_execute' | 'execute';
+export type AssistantIntentSource = 'chatgpt' | 'mcp' | 'local-ui' | 'mobile' | 'system';
+export type AssistantPlanStepStatus = 'planned' | 'submitted' | 'blocked' | 'skipped';
+export type AssistantRoutineStatus = 'enabled' | 'paused' | 'deleted';
+export type AssistantInboxItemStatus = 'unread' | 'read' | 'archived';
+
+export interface AssistantPlanStepInput {
+  stepId?: string;
+  pluginId: string;
+  actionId: string;
+  arguments?: Record<string, unknown>;
+  requestId?: string;
+  confirmAuthorization?: boolean;
+  confirmationText?: string;
+}
+
+export interface AssistantPlanStepResult {
+  stepId: string;
+  pluginId: string;
+  actionId: string;
+  status: AssistantPlanStepStatus;
+  risk: 'readonly' | 'workspace_write' | 'remote_write' | 'destructive' | 'unknown';
+  decision: 'allow' | 'approval_required' | 'reject';
+  reason: string;
+  requiredConfirmationText?: string;
+  job?: ExecutionJob;
+}
+
+export interface AssistantIntentInput {
+  utterance?: string;
+  source?: AssistantIntentSource;
+  mode?: AssistantIntentMode;
+  requestId?: string;
+  timezone?: string;
+  context?: Record<string, unknown>;
+  plan?: AssistantPlanStepInput[];
+  routine?: Partial<AssistantRoutineDraft>;
+  confirmRoutine?: boolean;
+}
+
+export interface AssistantRoutineDraft {
+  name: string;
+  naturalLanguageGoal: string;
+  scheduleText: string;
+  timezone?: string;
+  dataSources: string[];
+  output: 'assistant_inbox' | 'gmail_draft' | 'none';
+  allowedActions: string[];
+  forbiddenActions: string[];
+}
+
+export interface AssistantRoutine extends AssistantRoutineDraft {
+  schemaVersion: 1;
+  routineId: string;
+  status: AssistantRoutineStatus;
+  createdAt: string;
+  updatedAt: string;
+  lastRunAt?: string;
+  nextRunHint?: string;
+}
+
+export interface AssistantRoutinesStore {
+  schemaVersion: 1;
+  updatedAt: string;
+  routines: AssistantRoutine[];
+}
+
+export interface AssistantInboxItem {
+  schemaVersion: 1;
+  itemId: string;
+  kind: 'intent_result' | 'routine_result' | 'approval_request' | 'system_note';
+  status: AssistantInboxItemStatus;
+  title: string;
+  summary: string;
+  body?: string;
+  createdAt: string;
+  updatedAt: string;
+  source: AssistantIntentSource | 'routine' | 'system';
+  relatedRoutineId?: string;
+  relatedRequestId?: string;
+  jobIds: string[];
+  recommendations: string[];
+  data?: Record<string, unknown>;
+}
+
+export interface AssistantInboxStore {
+  schemaVersion: 1;
+  updatedAt: string;
+  items: AssistantInboxItem[];
+}
+
+export interface AssistantMemoryEntry {
+  key: string;
+  value: string;
+  updatedAt: string;
+  source?: string;
+}
+
+export interface AssistantMemoryStore {
+  schemaVersion: 1;
+  updatedAt: string;
+  entries: AssistantMemoryEntry[];
+}
+
+export interface AssistantIntentResult {
+  schemaVersion: 1;
+  accepted: boolean;
+  mode: AssistantIntentMode;
+  source: AssistantIntentSource;
+  requestId: string;
+  understoodIntent: string;
+  displayTitle: string;
+  displayText: string;
+  requiresConfirmation: boolean;
+  confirmationSummary?: string;
+  routineDraft?: AssistantRoutineDraft;
+  routine?: AssistantRoutine;
+  plan: AssistantPlanStepResult[];
+  inboxItem?: AssistantInboxItem;
+  clarifyingQuestions: string[];
+}
+
+export interface AssistantPolicyDecision {
+  decision: 'allow' | 'approval_required' | 'reject';
+  reason: string;
+  autoConfirmAuthorization: boolean;
+  requiredConfirmationText?: string;
+}
+
+export interface AssistantExecutionContext {
+  origin: ExecutionJobOrigin;
+  requestId: string;
+}

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

@@ -0,0 +1,347 @@
+import { spawnSync } from 'child_process';
+import { accessSync, constants, existsSync } from 'fs';
+import { createRequire } from 'module';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const require = createRequire(import.meta.url);
+const SCHEMA_VERSION = 1;
+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 ALLOWED_OPERATIONS = new Set<CodeGraphReadOperation>(['status', 'search', 'context', 'impact', 'file_dependencies']);
+
+export type CodeGraphReadOperation = 'status' | 'search' | 'context' | 'impact' | 'file_dependencies';
+export type CodeGraphProviderStatus = 'ready' | 'stale' | 'unavailable' | 'degraded';
+
+export interface CodeGraphNodeSummary {
+  id: string;
+  kind: string;
+  name: string;
+  qualifiedName: string;
+  filePath: string;
+  language: string;
+  startLine: number;
+  endLine: number;
+  signature?: string;
+}
+
+export interface CodeGraphEdgeSummary {
+  source: string;
+  target: string;
+  kind: string;
+  line?: number;
+  provenance?: string;
+}
+
+export interface CodeGraphIndexMetadata {
+  initialized: boolean;
+  lastIndexedAt: number | null;
+  buildVersion: string | null;
+  extractionVersion: number | null;
+  staleEngine: boolean;
+  changedFiles: {
+    added: string[];
+    modified: string[];
+    removed: string[];
+  };
+  /** CodeGraph SDK drift entries excluded by the repository's Git ignore authority. */
+  ignoredChangedFileCount?: number;
+  stats?: {
+    nodeCount: number;
+    edgeCount: number;
+    fileCount: number;
+    dbSizeBytes: number;
+    lastUpdated: number;
+  };
+  backend?: string;
+  journalMode?: string;
+}
+
+export interface CodeGraphReadRequest {
+  operation: CodeGraphReadOperation;
+  query?: string;
+  nodeId?: string;
+  filePath?: string;
+  limit?: number;
+  maxNodes?: number;
+  maxDepth?: number;
+}
+
+export interface CodeGraphReadProviderResponse {
+  schemaVersion: 1;
+  provider: 'codegraph';
+  operation: CodeGraphReadOperation;
+  ok: boolean;
+  status: CodeGraphProviderStatus;
+  metadata?: CodeGraphIndexMetadata;
+  result?: Record<string, unknown>;
+  error?: {
+    code: string;
+    message: string;
+  };
+  timingsMs: {
+    total: number;
+    process?: number;
+    open?: number;
+    query?: number;
+  };
+}
+
+interface SidecarSuccess {
+  schemaVersion: 1;
+  ok: true;
+  operation: CodeGraphReadOperation;
+  metadata: CodeGraphIndexMetadata;
+  result: Record<string, unknown>;
+  timingsMs?: { open?: number; query?: number };
+}
+
+interface SidecarFailure {
+  schemaVersion: 1;
+  ok: false;
+  operation?: CodeGraphReadOperation;
+  error: { code: string; message: string };
+  timingsMs?: { open?: number; query?: number };
+}
+
+type SidecarResponse = SidecarSuccess | SidecarFailure;
+
+function isExecutable(path: string): boolean {
+  try {
+    if (!existsSync(path)) return false;
+    accessSync(path, process.platform === 'win32' ? constants.F_OK : constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function boundedInteger(value: number | undefined, fallback: number, min: number, max: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
+
+export function resolveCodeGraphBundledRuntime(options: { runtimeRoot?: string } = {}): {
+  nodeExecutable: string;
+  sidecarPath: string;
+  libraryPath: string;
+  platformPackage: string;
+  source: 'release' | 'dependency';
+} {
+  const target = `${process.platform}-${process.arch}`;
+  const platformPackage = `@colbymchenry/codegraph-${target}`;
+  const runtimeRoot = options.runtimeRoot ?? 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');
+  if (isExecutable(releaseNode) && existsSync(releaseSidecar) && existsSync(releaseLibrary)) {
+    return {
+      nodeExecutable: releaseNode,
+      sidecarPath: releaseSidecar,
+      libraryPath: releaseLibrary,
+      platformPackage,
+      source: 'release',
+    };
+  }
+  let packageJson: string;
+  try {
+    packageJson = require.resolve(`${platformPackage}/package.json`);
+  } catch {
+    throw new Error(`CODEGRAPH_PLATFORM_BUNDLE_MISSING: ${platformPackage} is not installed`);
+  }
+  const nodeExecutable = join(dirname(packageJson), process.platform === 'win32' ? 'node.exe' : 'node');
+  if (!isExecutable(nodeExecutable)) {
+    throw new Error(`CODEGRAPH_BUNDLED_NODE_UNAVAILABLE: bundled Node runtime is missing for ${platformPackage}`);
+  }
+  const sidecarPath = fileURLToPath(new URL('./codegraph-sidecar.cjs', import.meta.url));
+  if (!existsSync(sidecarPath)) {
+    throw new Error('CODEGRAPH_SIDECAR_MISSING: packaged read-only sidecar could not be resolved');
+  }
+  const libraryPath = join(dirname(packageJson), 'lib', 'dist', 'index.js');
+  if (!existsSync(libraryPath)) {
+    throw new Error(`CODEGRAPH_LIBRARY_UNAVAILABLE: compiled library is missing for ${platformPackage}`);
+  }
+  return { nodeExecutable, sidecarPath, libraryPath, platformPackage, source: 'dependency' };
+}
+
+function minimalEnvironment(runtime: ReturnType<typeof resolveCodeGraphBundledRuntime>): NodeJS.ProcessEnv {
+  return Object.fromEntries(Object.entries({
+    PATH: dirname(runtime.nodeExecutable),
+    HOME: process.env.HOME,
+    TMPDIR: process.env.TMPDIR,
+    TEMP: process.env.TEMP,
+    TMP: process.env.TMP,
+    LANG: process.env.LANG,
+    LC_ALL: process.env.LC_ALL,
+    CODEGRAPH_TELEMETRY: '0',
+    DO_NOT_TRACK: '1',
+    CODEGRAPH_NO_DAEMON: '1',
+    FORGE_CODEGRAPH_LIBRARY_PATH: runtime.libraryPath,
+  }).filter((entry): entry is [string, string] => typeof entry[1] === 'string'));
+}
+
+function parseSidecarResponse(raw: string): SidecarResponse {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error('CODEGRAPH_PROTOCOL_ERROR: sidecar returned invalid JSON');
+  }
+  if (!parsed || typeof parsed !== 'object' || (parsed as { schemaVersion?: unknown }).schemaVersion !== SCHEMA_VERSION) {
+    throw new Error('CODEGRAPH_PROTOCOL_ERROR: sidecar returned an unsupported response');
+  }
+  return parsed as SidecarResponse;
+}
+
+function providerStatus(metadata: CodeGraphIndexMetadata): CodeGraphProviderStatus {
+  if (!metadata.initialized) return 'unavailable';
+  if (metadata.staleEngine) return 'stale';
+  if (metadata.changedFiles.added.length > 0 || metadata.changedFiles.modified.length > 0 || metadata.changedFiles.removed.length > 0) return 'stale';
+  return 'ready';
+}
+
+/**
+ * CodeGraph 1.0.1 deliberately discovers nested repositories below ignored
+ * directories. Its read-only change scan can then report those same paths as
+ * permanently added/removed relative to the owning repository. Ignore only
+ * paths that Git itself classifies as excluded; tracked changes still make the
+ * structural index stale and any Git probe failure keeps the SDK result.
+ */
+export function filterGitIgnoredCodeGraphChanges(
+  repoRoot: string,
+  metadata: CodeGraphIndexMetadata,
+): CodeGraphIndexMetadata {
+  const changed = [
+    ...metadata.changedFiles.added,
+    ...metadata.changedFiles.modified,
+    ...metadata.changedFiles.removed,
+  ];
+  if (changed.length === 0) return metadata;
+  const git = spawnSync('git', ['-C', resolve(repoRoot), 'check-ignore', '--stdin', '-z'], {
+    input: `${changed.join('\0')}\0`,
+    encoding: 'utf8',
+    env: {
+      PATH: process.env.PATH,
+      HOME: process.env.HOME,
+      GIT_TERMINAL_PROMPT: '0',
+      GIT_CONFIG_NOSYSTEM: '1',
+      CI: '1',
+    },
+    timeout: 5_000,
+    maxBuffer: 512 * 1024,
+    windowsHide: true,
+  });
+  if (git.error || (git.status !== 0 && git.status !== 1)) return metadata;
+  const ignored = new Set(String(git.stdout ?? '').split('\0').filter(Boolean));
+  if (ignored.size === 0) return metadata;
+  return {
+    ...metadata,
+    changedFiles: {
+      added: metadata.changedFiles.added.filter((path) => !ignored.has(path)),
+      modified: metadata.changedFiles.modified.filter((path) => !ignored.has(path)),
+      removed: metadata.changedFiles.removed.filter((path) => !ignored.has(path)),
+    },
+    ignoredChangedFileCount: ignored.size,
+  };
+}
+
+function errorResponse(operation: CodeGraphReadOperation, code: string, message: string, total: number): CodeGraphReadProviderResponse {
+  const unavailable = code.includes('MISSING') || code.includes('UNAVAILABLE') || code.includes('NOT_INITIALIZED');
+  return {
+    schemaVersion: 1,
+    provider: 'codegraph',
+    operation,
+    ok: false,
+    status: unavailable ? 'unavailable' : 'degraded',
+    error: { code, message: message.slice(0, 1_000) },
+    timingsMs: { total },
+  };
+}
+
+export function queryCodeGraphReadProvider(
+  repoRoot: string,
+  request: CodeGraphReadRequest,
+  options: { timeoutMs?: number } = {},
+): 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);
+    const [code] = message.split(':', 1);
+    return errorResponse(request.operation, code || 'CODEGRAPH_RUNTIME_UNAVAILABLE', message, performance.now() - startedAt);
+  }
+
+  const normalizedRequest = {
+    schemaVersion: SCHEMA_VERSION,
+    operation: request.operation,
+    projectRoot: resolve(repoRoot),
+    ...(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),
+  };
+  const input = JSON.stringify(normalizedRequest);
+  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);
+  }
+
+  const processStartedAt = performance.now();
+  const execution = spawnSync(runtime.nodeExecutable, [runtime.sidecarPath], {
+    cwd: resolve(repoRoot),
+    input,
+    encoding: 'utf8',
+    env: minimalEnvironment(runtime),
+    timeout: boundedInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 1_000, 60_000),
+    maxBuffer: MAX_RESPONSE_BYTES,
+    windowsHide: true,
+    shell: false,
+  });
+  const processMs = performance.now() - processStartedAt;
+  if (execution.error) {
+    const code = (execution.error as NodeJS.ErrnoException).code === 'ETIMEDOUT' ? 'CODEGRAPH_TIMEOUT' : 'CODEGRAPH_START_FAILED';
+    return errorResponse(request.operation, code, execution.error.message, performance.now() - startedAt);
+  }
+  if (Buffer.byteLength(execution.stdout ?? '') > MAX_RESPONSE_BYTES) {
+    return errorResponse(request.operation, 'CODEGRAPH_RESPONSE_TOO_LARGE', 'CodeGraph response exceeded the bounded output limit.', performance.now() - startedAt);
+  }
+  if (execution.status !== 0) {
+    const stderr = String(execution.stderr ?? '').slice(-MAX_STDERR_CHARS);
+    return errorResponse(request.operation, 'CODEGRAPH_SIDECAR_FAILED', stderr || `CodeGraph sidecar exited with status ${String(execution.status)}`, performance.now() - startedAt);
+  }
+
+  let parsed: SidecarResponse;
+  try {
+    parsed = parseSidecarResponse(String(execution.stdout ?? ''));
+  } catch (error) {
+    return errorResponse(request.operation, 'CODEGRAPH_PROTOCOL_ERROR', error instanceof Error ? error.message : String(error), performance.now() - startedAt);
+  }
+  if (!parsed.ok) {
+    return errorResponse(request.operation, parsed.error.code, parsed.error.message, performance.now() - startedAt);
+  }
+  const metadata = filterGitIgnoredCodeGraphChanges(repoRoot, parsed.metadata);
+  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(processMs * 100) / 100,
+      ...(typeof parsed.timingsMs?.open === 'number' ? { open: parsed.timingsMs.open } : {}),
+      ...(typeof parsed.timingsMs?.query === 'number' ? { query: parsed.timingsMs.query } : {}),
+    },
+  };
+}

package/src/runtime/context/codegraph-sidecar.cjs

@@ -0,0 +1,207 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { performance } = require('perf_hooks');
+
+const SCHEMA_VERSION = 1;
+const ALLOWED_OPERATIONS = new Set(['status', 'search', 'context', 'impact', 'file_dependencies']);
+
+function clamp(value, fallback, min, max) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return fallback;
+  return Math.min(Math.max(Math.trunc(value), min), max);
+}
+
+function fail(operation, code, message) {
+  process.stdout.write(JSON.stringify({
+    schemaVersion: SCHEMA_VERSION,
+    ok: false,
+    operation,
+    error: { code, message: String(message).slice(0, 1000) },
+  }));
+  process.exitCode = 1;
+}
+
+function nodeSummary(node) {
+  return {
+    id: node.id,
+    kind: node.kind,
+    name: node.name,
+    qualifiedName: node.qualifiedName,
+    filePath: node.filePath,
+    language: node.language,
+    startLine: node.startLine,
+    endLine: node.endLine,
+    ...(node.signature ? { signature: String(node.signature).slice(0, 1000) } : {}),
+  };
+}
+
+function edgeSummary(edge) {
+  return {
+    source: edge.source,
+    target: edge.target,
+    kind: edge.kind,
+    ...(typeof edge.line === 'number' ? { line: edge.line } : {}),
+    ...(edge.provenance ? { provenance: edge.provenance } : {}),
+  };
+}
+
+function subgraphSummary(subgraph, maxNodes) {
+  const nodes = Array.from(subgraph.nodes.values()).slice(0, maxNodes);
+  const nodeIds = new Set(nodes.map((node) => node.id));
+  const edges = subgraph.edges
+    .filter((edge) => nodeIds.has(edge.source) && nodeIds.has(edge.target))
+    .slice(0, maxNodes * 3);
+  const byId = new Map(nodes.map((node) => [node.id, node]));
+  return {
+    nodes: nodes.map(nodeSummary),
+    edges: edges.map(edgeSummary),
+    roots: subgraph.roots.filter((id) => nodeIds.has(id)).slice(0, 20),
+    entryPoints: subgraph.roots.map((id) => byId.get(id)).filter(Boolean).slice(0, 12).map(nodeSummary),
+    relatedFiles: Array.from(new Set(nodes.map((node) => node.filePath).filter(Boolean))).slice(0, 80),
+    ...(subgraph.confidence ? { confidence: subgraph.confidence } : {}),
+    truncated: subgraph.nodes.size > nodes.length || subgraph.edges.length > edges.length,
+  };
+}
+
+function metadata(graph) {
+  const changed = graph.getChangedFiles();
+  const build = graph.getIndexBuildInfo();
+  const stats = graph.getStats();
+  return {
+    initialized: true,
+    lastIndexedAt: graph.getLastIndexedAt(),
+    buildVersion: build.version,
+    extractionVersion: build.extractionVersion,
+    staleEngine: graph.isIndexStale(),
+    changedFiles: {
+      added: changed.added.slice(0, 50),
+      modified: changed.modified.slice(0, 50),
+      removed: changed.removed.slice(0, 50),
+    },
+    stats: {
+      nodeCount: stats.nodeCount,
+      edgeCount: stats.edgeCount,
+      fileCount: stats.fileCount,
+      dbSizeBytes: stats.dbSizeBytes,
+      lastUpdated: stats.lastUpdated,
+    },
+    backend: String(graph.getBackend()),
+    journalMode: String(graph.getJournalMode()),
+  };
+}
+
+async function main() {
+  let request;
+  try {
+    request = JSON.parse(fs.readFileSync(0, 'utf8'));
+  } catch (error) {
+    fail(undefined, 'CODEGRAPH_REQUEST_INVALID', error instanceof Error ? error.message : error);
+    return;
+  }
+  const operation = request && request.operation;
+  if (!request || request.schemaVersion !== SCHEMA_VERSION || !ALLOWED_OPERATIONS.has(operation)) {
+    fail(operation, 'CODEGRAPH_OPERATION_NOT_ALLOWED', `Unsupported read operation: ${String(operation)}`);
+    return;
+  }
+  if (typeof request.projectRoot !== 'string' || !path.isAbsolute(request.projectRoot)) {
+    fail(operation, 'CODEGRAPH_PROJECT_ROOT_INVALID', 'projectRoot must be an absolute path selected by Forge.');
+    return;
+  }
+
+  let library;
+  try {
+    const configuredLibrary = process.env.FORGE_CODEGRAPH_LIBRARY_PATH;
+    library = require(configuredLibrary || '@colbymchenry/codegraph');
+    if (typeof library.setLogger === 'function' && library.silentLogger) library.setLogger(library.silentLogger);
+  } catch (error) {
+    fail(operation, 'CODEGRAPH_LIBRARY_UNAVAILABLE', error instanceof Error ? error.message : error);
+    return;
+  }
+  const CodeGraph = library.CodeGraph || library.default;
+  if (!CodeGraph || typeof CodeGraph.open !== 'function') {
+    fail(operation, 'CODEGRAPH_LIBRARY_UNAVAILABLE', 'CodeGraph SDK entry point is unavailable.');
+    return;
+  }
+  if (!CodeGraph.isInitialized(request.projectRoot)) {
+    process.stdout.write(JSON.stringify({
+      schemaVersion: SCHEMA_VERSION,
+      ok: true,
+      operation,
+      metadata: {
+        initialized: false,
+        lastIndexedAt: null,
+        buildVersion: null,
+        extractionVersion: null,
+        staleEngine: false,
+        changedFiles: { added: [], modified: [], removed: [] },
+      },
+      result: {},
+      timingsMs: { open: 0, query: 0 },
+    }));
+    return;
+  }
+
+  let graph;
+  const openStartedAt = performance.now();
+  try {
+    graph = await CodeGraph.open(request.projectRoot, { sync: false, readOnly: true });
+  } catch (error) {
+    fail(operation, 'CODEGRAPH_OPEN_FAILED', error instanceof Error ? error.message : error);
+    return;
+  }
+  const openMs = Math.round((performance.now() - openStartedAt) * 100) / 100;
+
+  try {
+    const queryStartedAt = performance.now();
+    const limit = clamp(request.limit, 12, 1, 40);
+    const maxNodes = clamp(request.maxNodes, 40, 1, 80);
+    const maxDepth = clamp(request.maxDepth, 2, 1, 5);
+    let result = {};
+    if (operation === 'search') {
+      if (typeof request.query !== 'string' || !request.query.trim()) throw new Error('CODEGRAPH_QUERY_REQUIRED');
+      result = {
+        results: graph.searchNodes(request.query.trim(), { limit }).map((entry) => ({
+          node: nodeSummary(entry.node),
+          score: entry.score,
+          highlights: Array.isArray(entry.highlights) ? entry.highlights.slice(0, 8).map((value) => String(value).slice(0, 500)) : [],
+        })),
+      };
+    } else if (operation === 'context') {
+      if (typeof request.query !== 'string' || !request.query.trim()) throw new Error('CODEGRAPH_QUERY_REQUIRED');
+      const subgraph = await graph.findRelevantContext(request.query.trim(), {
+        searchLimit: Math.min(limit, 12),
+        traversalDepth: Math.min(maxDepth, 3),
+        maxNodes,
+      });
+      result = subgraphSummary(subgraph, maxNodes);
+    } else if (operation === 'impact') {
+      if (typeof request.nodeId !== 'string' || !request.nodeId.trim()) throw new Error('CODEGRAPH_NODE_ID_REQUIRED');
+      result = subgraphSummary(graph.getImpactRadius(request.nodeId.trim(), maxDepth), maxNodes);
+    } else if (operation === 'file_dependencies') {
+      if (typeof request.filePath !== 'string' || !request.filePath.trim()) throw new Error('CODEGRAPH_FILE_PATH_REQUIRED');
+      result = {
+        filePath: request.filePath.trim(),
+        dependencies: graph.getFileDependencies(request.filePath.trim()).slice(0, 100),
+        dependents: graph.getFileDependents(request.filePath.trim()).slice(0, 100),
+      };
+    } else if (operation === 'status') {
+      result = {};
+    }
+    const queryMs = Math.round((performance.now() - queryStartedAt) * 100) / 100;
+    process.stdout.write(JSON.stringify({
+      schemaVersion: SCHEMA_VERSION,
+      ok: true,
+      operation,
+      metadata: metadata(graph),
+      result,
+      timingsMs: { open: openMs, query: queryMs },
+    }));
+  } catch (error) {
+    fail(operation, 'CODEGRAPH_QUERY_FAILED', error instanceof Error ? error.message : error);
+  } finally {
+    try { graph.close(); } catch (_) { /* no-op */ }
+  }
+}
+
+main().catch((error) => fail(undefined, 'CODEGRAPH_SIDECAR_UNHANDLED', error instanceof Error ? error.message : error));