@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/context/direct-controller-learning.ts

@@ -0,0 +1,298 @@
+import { createHash } from 'crypto';
+import {
+  memoryAddressKey,
+  parseMemoryAddressKey,
+  memoryDraftFromLearningSignal,
+  recordCognitiveMemory,
+  type CognitiveWriteAuthorityPort,
+  type LearningSignal,
+  type MemoryUnit,
+} from '../../../packages/kernel/cognition/api/index';
+import { readForgeInstanceIdentity, type ScopeRef } from '../../../packages/kernel/identity/api/index';
+import { FORGE_INSTANCE_SCOPE_KEY } from '../../cli/repositories/controller-home';
+import type { RepositoryRecord } from '../../cli/repositories/types';
+import { cognitionMemoryStore, cognitionReadPort, recordCognitiveUsageObservation, type CognitiveUsageRejectionKind } from '../control-plane/persistence/cognition-store';
+import { resolveProjectForRepositoryPlacement } from '../control-plane/workspace/workspace-store';
+import { getWorkContract } from '../../../packages/kernel/work/api/index';
+import { cognitiveScopesForWork } from '../control-plane/persistence/experience-store';
+import { findPluginActionReceipt } from '../plugins/store';
+import {
+  associateStoredMemories,
+  consolidateAffectedMemories,
+  CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS,
+  type ControllerLearningSignalDraft,
+} from './automatic-learning';
+
+export interface DirectControllerLearningResult {
+  storedMemoryIds: string[];
+  associatedEdgeCount: number;
+  consolidatedMemoryIds: string[];
+  scopes: ScopeRef[];
+}
+
+function sameScope(left: ScopeRef, right: ScopeRef): boolean {
+  return left.kind === right.kind && left.id === right.id;
+}
+
+export function directLearningScopes(
+  controllerHome: string,
+  repository: Pick<RepositoryRecord, 'repoId' | 'activeCheckoutId'>,
+  workId?: string,
+): ScopeRef[] {
+  if (workId) {
+    const work = getWorkContract({ controllerHome, repoId: repository.repoId }, workId);
+    if (!work) throw new Error(`WORK_NOT_FOUND: ${workId}`);
+    return cognitiveScopesForWork(work, controllerHome);
+  }
+  const instance = readForgeInstanceIdentity(controllerHome);
+  if (!instance) throw new Error('COGNITION_DIRECT_LEARNING_FORGE_INSTANCE_REQUIRED');
+  const project = resolveProjectForRepositoryPlacement({
+    controllerHome,
+    forgeInstanceId: instance.instanceId,
+    repositoryId: repository.repoId,
+    checkoutId: repository.activeCheckoutId,
+  });
+  if (!project) throw new Error('COGNITION_DIRECT_LEARNING_PROJECT_PLACEMENT_REQUIRED');
+  return [
+    { schemaVersion: 1, kind: 'project', id: project.projectId },
+    { schemaVersion: 1, kind: 'workspace', id: project.workspaceId },
+  ];
+}
+
+function semanticSignalId(signal: ControllerLearningSignalDraft, scope: ScopeRef): string {
+  const concepts = [...new Set(signal.concepts.map(value => value.trim()).filter(Boolean))].sort();
+  const identity = JSON.stringify({
+    scope: `${scope.kind}:${scope.id}`,
+    kind: signal.kind,
+    valence: signal.valence,
+    summary: signal.summary,
+    concepts,
+    admissionSource: signal.admissionSource,
+    portability: signal.portability,
+  });
+  return createHash('sha256').update(identity).digest('hex').slice(0, 32);
+}
+
+function directSourceId(input: {
+  principalId?: string;
+  sessionId?: string;
+  controllerInstanceId?: string;
+  controllerType?: string;
+}): string {
+  const identity = [
+    input.principalId?.trim() ?? '',
+    input.controllerType?.trim() ?? '',
+    input.controllerInstanceId?.trim() ?? '',
+    input.sessionId?.trim() ?? '',
+  ].join(':');
+  return `mcp-learning:${createHash('sha256').update(identity || 'anonymous-controller').digest('hex').slice(0, 24)}`;
+}
+
+function directLearningAuthority(input: {
+  controllerHome: string;
+  repository: Pick<RepositoryRecord, 'repoId'>;
+  scopes: readonly ScopeRef[];
+  principalId?: string;
+  sourceId: string;
+  sourceWorkId?: string;
+}): CognitiveWriteAuthorityPort {
+  const scopeAllowed = (scope: ScopeRef) => input.scopes.some(candidate => sameScope(candidate, scope));
+  return {
+    assertMemoryWrite(memory: MemoryUnit) {
+      if (!scopeAllowed(memory.scope)
+        || memory.provenance.sourceKind !== 'controller'
+        || memory.provenance.sourceId !== input.sourceId
+        || memory.provenance.sourceWorkId !== input.sourceWorkId
+        || memory.provenance.sourceRoundId) {
+        throw new Error('COGNITION_DIRECT_LEARNING_AUTHORITY_INVALID');
+      }
+      if (memory.scope.kind === 'workspace' && !memory.facets.includes('portability.portable')) {
+        throw new Error('COGNITION_DIRECT_LEARNING_WORKSPACE_PORTABILITY_REQUIRED');
+      }
+    },
+    assertEdgeWrite() {
+      throw new Error('COGNITION_DIRECT_LEARNING_EDGE_NOT_ALLOWED');
+    },
+    evidenceAvailable(ref, scope) {
+      if (!scopeAllowed(scope)) return false;
+      const receipt = findPluginActionReceipt(input.controllerHome, ref);
+      if (!receipt) return false;
+      if (receipt.repoId === input.repository.repoId || receipt.workRepoId === input.repository.repoId) return true;
+      const principal = input.principalId?.trim();
+      return receipt.scopeKey === FORGE_INSTANCE_SCOPE_KEY
+        && Boolean(principal)
+        && receipt.origin?.actor === principal;
+    },
+  };
+}
+
+/**
+ * Persist semantic learning selected by the model without creating a learning lifecycle.
+ *
+ * The caller supplies meaning plus an optional already-existing Work identity. Forge derives
+ * reachable semantic scope, source identity and time. Work provenance never fabricates a
+ * ControllerRound; ControllerRound authority remains intentionally absent.
+ */
+export interface DirectControllerLearningFeedbackDraft {
+  memoryAddress: string;
+  decision: 'used' | 'rejected';
+  reason: string;
+  rejectionKind?: CognitiveUsageRejectionKind;
+}
+
+export interface DirectControllerLearningFeedbackResult {
+  observationIds: string[];
+  scopes: ScopeRef[];
+}
+
+export function recordDirectControllerLearningFeedback(input: {
+  controllerHome: string;
+  repository: Pick<RepositoryRecord, 'repoId' | 'activeCheckoutId'>;
+  feedback: readonly DirectControllerLearningFeedbackDraft[];
+  principalId?: string;
+  sessionId?: string;
+  controllerInstanceId?: string;
+  now?: string;
+  workId?: string;
+}): DirectControllerLearningFeedbackResult {
+  if (!input.feedback.length || input.feedback.length > 32) throw new Error('COGNITION_DIRECT_FEEDBACK_ITEMS_INVALID');
+  const principalId = input.principalId?.trim();
+  if (!principalId) throw new Error('COGNITION_DIRECT_FEEDBACK_PRINCIPAL_REQUIRED');
+  const interactionId = input.sessionId?.trim() || input.controllerInstanceId?.trim();
+  if (!interactionId) throw new Error('COGNITION_DIRECT_FEEDBACK_SESSION_REQUIRED');
+  const scopes = directLearningScopes(input.controllerHome, input.repository, input.workId);
+  const allowedScopes = new Set(scopes.map(scope => `${scope.kind}:${scope.id}`));
+  const now = input.now ?? new Date().toISOString();
+  const read = cognitionReadPort(input.controllerHome);
+  const observations = input.feedback.map((draft, index) => {
+    const address = parseMemoryAddressKey(draft.memoryAddress);
+    if (!address || !allowedScopes.has(`${address.scope.kind}:${address.scope.id}`)) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_MEMORY_SCOPE_INVALID: ${index}`);
+    }
+    if (!read.readByAddresses([address]).length) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_MEMORY_NOT_FOUND: ${index}`);
+    }
+    const reason = draft.reason.trim();
+    if (!reason || reason.length > 1_000) throw new Error(`COGNITION_DIRECT_FEEDBACK_REASON_INVALID: ${index}`);
+    if (draft.decision === 'rejected' && !draft.rejectionKind) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_REJECTION_KIND_REQUIRED: ${index}`);
+    }
+    if (draft.decision === 'used' && draft.rejectionKind) {
+      throw new Error(`COGNITION_DIRECT_FEEDBACK_REJECTION_KIND_UNEXPECTED: ${index}`);
+    }
+    const observationId = `usage:${createHash('sha256')
+      .update(JSON.stringify({
+        actor: principalId,
+        interaction: interactionId,
+        address: memoryAddressKey(address),
+        decision: draft.decision,
+        rejectionKind: draft.rejectionKind ?? '',
+        reason,
+      }))
+      .digest('hex').slice(0, 32)}`;
+    return recordCognitiveUsageObservation(input.controllerHome, {
+      observationId,
+      address,
+      actorId: principalId,
+      decision: draft.decision,
+      reason,
+      ...(draft.rejectionKind ? { rejectionKind: draft.rejectionKind } : {}),
+      observedAt: now,
+    });
+  });
+  return { observationIds: observations.map(item => item.observationId), scopes };
+}
+
+export function persistDirectControllerLearning(input: {
+  controllerHome: string;
+  repository: Pick<RepositoryRecord, 'repoId' | 'activeCheckoutId'>;
+  signals: readonly ControllerLearningSignalDraft[];
+  principalId?: string;
+  sessionId?: string;
+  controllerInstanceId?: string;
+  controllerType?: string;
+  workId?: string;
+  now?: string;
+}): DirectControllerLearningResult {
+  if (!input.signals.length || input.signals.length > CONTROLLER_LEARNING_SIGNAL_ENVELOPE_MAX_ITEMS) {
+    throw new Error('COGNITION_DIRECT_LEARNING_SIGNALS_INVALID');
+  }
+  const scopes = directLearningScopes(input.controllerHome, input.repository, input.workId);
+  const observedAt = input.now ?? new Date().toISOString();
+  const sourceId = directSourceId(input);
+  const projectScope = scopes.find(scope => scope.kind === 'project')!;
+  const workspaceScope = scopes.find(scope => scope.kind === 'workspace')!;
+  const store = cognitionMemoryStore(input.controllerHome);
+  const authority = directLearningAuthority({
+    controllerHome: input.controllerHome,
+    repository: input.repository,
+    scopes,
+    principalId: input.principalId,
+    sourceId,
+    sourceWorkId: input.workId,
+  });
+
+  const drafts = input.signals.map(signal => {
+    const scope = scopes.find(candidate => candidate.kind === signal.scopeKind)
+      ?? (signal.scopeKind === 'project' ? projectScope : signal.scopeKind === 'workspace' ? workspaceScope : undefined);
+    if (!scope) {
+      throw new Error(`COGNITION_LEARNING_SCOPE_UNREACHABLE: ${signal.scopeKind}`);
+    }
+    const id = semanticSignalId(signal, scope);
+    const learning: LearningSignal = {
+      schemaVersion: 1,
+      id: `direct:${id}`,
+      scope,
+      kind: signal.kind,
+      valence: signal.valence,
+      summary: signal.summary,
+      concepts: [...new Set(signal.concepts.map(value => value.trim()).filter(Boolean))],
+      facets: [...new Set(signal.facets.map(value => value.trim()).filter(Boolean))],
+      admissionSource: signal.admissionSource,
+      portability: signal.portability,
+      salience: signal.salience,
+      confidence: signal.confidence,
+      utility: signal.utility,
+      sourceKind: 'controller',
+      sourceId,
+      observedAt,
+      evidenceRefs: [...new Set(signal.evidenceRefs)],
+      counterEvidenceRefs: [...new Set(signal.counterEvidenceRefs)],
+      ...(signal.expiresAt ? { expiresAt: signal.expiresAt } : {}),
+    };
+    const draft = memoryDraftFromLearningSignal(learning);
+    return input.workId ? {
+      ...draft,
+      provenance: {
+        ...draft.provenance,
+        sourceWorkId: input.workId,
+      },
+    } : draft;
+  });
+
+  // Validate all evidence before any write so a multi-signal call cannot partially commit.
+  for (const draft of drafts) {
+    authority.assertMemoryWrite({ ...draft, schemaVersion: 1, revision: 1 });
+    for (const ref of [...draft.provenance.evidenceRefs, ...draft.counterEvidenceRefs]) {
+      if (!authority.evidenceAvailable(ref, draft.scope)) {
+        throw new Error(`COGNITION_DIRECT_LEARNING_EVIDENCE_UNAVAILABLE: ${ref}`);
+      }
+    }
+  }
+
+  const stored = store.transaction(() => drafts.map(draft =>
+    recordCognitiveMemory(store, authority, draft)));
+  const associatedEdgeCount = associateStoredMemories({
+    controllerHome: input.controllerHome,
+    memories: stored,
+    now: observedAt,
+  });
+  const consolidatedMemoryIds = scopes.flatMap(scope =>
+    consolidateAffectedMemories(input.controllerHome, scope, stored, observedAt).map(candidate => candidate.memory.id));
+  return {
+    storedMemoryIds: stored.map(memory => memory.id),
+    associatedEdgeCount,
+    consolidatedMemoryIds: [...new Set(consolidatedMemoryIds)],
+    scopes,
+  };
+}

package/src/runtime/context/generic-lsp-provider.ts

@@ -266,7 +266,7 @@ export class GenericLspSemanticProvider implements SemanticNavigationProvider {
       return requests.map(() => ({
         ok: false,
         code: 'LSP_SEMANTIC_READ_SCOPE_UNSUPPORTED',
-        message: `External ${this.descriptor.id} navigation is restricted to the controller read profile; use lexical/CodeGraph evidence under narrower read policies.`,
+        message: `External ${this.descriptor.id} navigation is restricted to the controller read profile; use bounded lexical/raw source evidence under narrower read policies.`,
       }));
     }
     const outcomes: Array<SemanticNavigationOutcome | undefined> = new Array(requests.length);

package/src/runtime/context/semantic-navigation-contract.ts

@@ -25,6 +25,8 @@ export interface SemanticNavigationResult {
   target: { path: string; line: number; column: number };
   locations: SemanticNavigationLocation[];
   policyDeniedReads?: number;
+  /** Denied requested/material reads, excluding incidental dependency probes. */
+  materialPolicyDeniedReads?: number;
   details?: Record<string, unknown>;
 }
 
@@ -32,10 +34,19 @@ export type SemanticNavigationOutcome =
   | { ok: true; result: SemanticNavigationResult }
   | { ok: false; code: string; message: string };
 
+export interface SemanticNavigationReadPolicy {
+  profile: string;
+  readGlobs: readonly string[];
+  denyGlobs: readonly string[];
+  maxFileBytes: number;
+}
+
 export interface SemanticNavigationAccess {
   cacheScope: string;
   sourceIdentity?: string;
   profile: string;
+  /** Serializable policy used by disposable semantic sidecars. */
+  readPolicy?: SemanticNavigationReadPolicy;
   allowRepositoryPath(relativePath: string): boolean;
 }
 
@@ -59,3 +70,8 @@ export interface IndexedSemanticNavigationOutcome {
   index: number;
   outcome: SemanticNavigationOutcome;
 }
+
+/** Dependency probes rejected by policy cannot certify missing requested source relationships. */
+export function isIncidentalSemanticDependencyProbe(path: string): boolean {
+  return /(?:^|\/)node_modules\/[^/]+/.test(path.replace(/\\/g, '/'));
+}

package/src/runtime/context/semantic-navigation.ts

@@ -1,5 +1,5 @@
 import { extname } from 'path';
-import { navigateTypeScriptSymbol } from './typescript-navigation';
+import { navigateTypeScriptInSidecar } from './typescript-navigation-process';
 import { navigateSwiftSymbols } from './swift-navigation';
 import { GenericLspSemanticProvider, type GenericLspProviderDescriptor } from './generic-lsp-provider';
 
@@ -25,39 +25,11 @@ const typeScriptProvider: SemanticNavigationProvider = {
     return extensionSupported && (!request.language || request.language.toLowerCase() === 'typescript');
   },
   async navigate(repoRoot, requests, access) {
-    return requests.map((request) => {
-      let policyDeniedReads = 0;
-      try {
-        const result = navigateTypeScriptSymbol(repoRoot, {
-          navigation: request.navigation,
-          path: request.path,
-          line: request.line,
-          column: request.column,
-          tsconfigPath: request.tsconfigPath,
-        }, {
-          cacheScope: access.cacheScope,
-          sourceIdentity: access.sourceIdentity,
-          allowRepositoryPath: (relativePath) => {
-            const allowed = access.allowRepositoryPath(relativePath);
-            if (!allowed) policyDeniedReads += 1;
-            return allowed;
-          },
-        });
-        return {
-          ok: true,
-          result: {
-            providerId: 'typescript-language-service',
-            language: 'typescript',
-            navigation: result.navigation,
-            target: result.target,
-            locations: result.locations,
-            policyDeniedReads,
-          },
-        } satisfies SemanticNavigationOutcome;
-      } catch (error) {
-        return { ok: false, code: 'SEMANTIC_NAVIGATION_FAILED', message: error instanceof Error ? error.message : String(error) } satisfies SemanticNavigationOutcome;
-      }
-    });
+    // A Forge-sized TypeScript LanguageService can return its live heap after
+    // dispose() while JSC/WebKit keeps the expanded allocator resident. Keep
+    // that allocator lifetime out of the canonical Runtime: one bounded batch
+    // runs in one short-lived sidecar and the OS reclaims it on process exit.
+    return navigateTypeScriptInSidecar(repoRoot, requests, access);
   },
 };
 
@@ -73,7 +45,7 @@ const swiftProvider: SemanticNavigationProvider = {
       if (request.tsconfigPath) {
         invalid.set(index, { ok: false, code: 'SWIFT_SEMANTIC_TSCONFIG_UNSUPPORTED', message: 'tsconfig_path applies only to TypeScript semantic navigation.' });
       } else if (access.profile !== 'controller') {
-        invalid.set(index, { ok: false, code: 'SWIFT_SEMANTIC_READ_SCOPE_UNSUPPORTED', message: 'External SourceKit-LSP navigation is restricted to the controller read profile; use lexical/CodeGraph evidence under narrower read policies.' });
+        invalid.set(index, { ok: false, code: 'SWIFT_SEMANTIC_READ_SCOPE_UNSUPPORTED', message: 'External SourceKit-LSP navigation is restricted to the controller read profile; use bounded lexical/raw source evidence under narrower read policies.' });
       } else {
         eligible.push({ index, request });
       }

package/src/runtime/context/typescript-navigation-process.ts

@@ -0,0 +1,145 @@
+import { existsSync, lstatSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { runProcess } from '../../effects/process-runner';
+import { resolveBunExecutable } from '../shared/process-environment';
+import type {
+  SemanticNavigationAccess,
+  SemanticNavigationOutcome,
+  SemanticNavigationRequest,
+} from './semantic-navigation-contract';
+
+const TYPESCRIPT_NAVIGATION_SIDECAR_ENTRYPOINT = 'forge-typescript-navigation' as const;
+const TYPESCRIPT_NAVIGATION_TIMEOUT_MS = 60_000;
+const TYPESCRIPT_NAVIGATION_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+
+interface SidecarResponse {
+  schemaVersion: 1;
+  outcomes: SemanticNavigationOutcome[];
+}
+
+interface SourceSymbolsSidecarResponse {
+  schemaVersion: 1;
+  symbols: Array<{ startLine: number; endLine: number; kind: string; name?: string; enclosing?: string }>;
+}
+
+interface SidecarManifestRecord {
+  typescriptNavigationEntrypoint?: unknown;
+  typescriptNavigationArtifactIdentity?: unknown;
+}
+
+function releaseManifestArgument(argv: readonly string[]): string | undefined {
+  const index = argv.indexOf('--release-manifest');
+  const value = index >= 0 ? argv[index + 1]?.trim() : undefined;
+  return value ? resolve(value) : undefined;
+}
+
+export function resolveTypeScriptNavigationSidecarCommand(
+  argv: readonly string[] = process.argv,
+): { executable: string; args: string[]; cwd?: string } {
+  const manifestPath = releaseManifestArgument(argv);
+  if (manifestPath) {
+    const parsed = JSON.parse(readFileSync(manifestPath, 'utf8')) as SidecarManifestRecord;
+    if (parsed.typescriptNavigationEntrypoint !== TYPESCRIPT_NAVIGATION_SIDECAR_ENTRYPOINT) {
+      throw new Error('TYPESCRIPT_NAVIGATION_SIDECAR_MANIFEST_MISSING');
+    }
+    const identity = typeof parsed.typescriptNavigationArtifactIdentity === 'string'
+      ? parsed.typescriptNavigationArtifactIdentity.trim()
+      : '';
+    if (!/^sha256:[a-f0-9]{64}$/i.test(identity)) {
+      throw new Error('TYPESCRIPT_NAVIGATION_SIDECAR_IDENTITY_INVALID');
+    }
+    const executable = join(dirname(manifestPath), TYPESCRIPT_NAVIGATION_SIDECAR_ENTRYPOINT);
+    if (!existsSync(executable)) throw new Error('TYPESCRIPT_NAVIGATION_SIDECAR_MISSING');
+    const status = lstatSync(executable);
+    if (status.isSymbolicLink() || !status.isFile() || (status.mode & 0o111) === 0) {
+      throw new Error('TYPESCRIPT_NAVIGATION_SIDECAR_NOT_EXECUTABLE');
+    }
+    return { executable, args: [], cwd: dirname(manifestPath) };
+  }
+
+  // Construct the development-only path at runtime. A literal new URL() to the
+  // .ts sidecar makes Bun bundle that file as an asset and drags the TypeScript
+  // compiler graph back into the long-lived Runtime.
+  const entry = resolve(process.cwd(), 'adapters', 'mcp', 'runtime-gateway', 'typescript-navigation-sidecar.ts');
+  if (!existsSync(entry)) throw new Error('TYPESCRIPT_NAVIGATION_SOURCE_SIDECAR_MISSING');
+  return {
+    executable: resolveBunExecutable(process.execPath, process.env),
+    args: [entry],
+    cwd: dirname(entry),
+  };
+}
+
+function failedOutcomes(requests: readonly SemanticNavigationRequest[], code: string, message: string): SemanticNavigationOutcome[] {
+  return requests.map(() => ({ ok: false as const, code, message }));
+}
+
+export function extractTypeScriptSourceSymbolsInSidecar(
+  path: string,
+  source: string,
+): SourceSymbolsSidecarResponse['symbols'] {
+  const command = resolveTypeScriptNavigationSidecarCommand();
+  const executed = runProcess(command.executable, command.args, {
+    cwd: command.cwd ?? process.cwd(),
+    input: JSON.stringify({ schemaVersion: 1, operation: 'source_symbols', path, source }),
+    timeoutMs: TYPESCRIPT_NAVIGATION_TIMEOUT_MS,
+    maxOutputBytes: TYPESCRIPT_NAVIGATION_MAX_OUTPUT_BYTES,
+  });
+  if (!executed.ok) {
+    throw new Error(`TYPESCRIPT_SOURCE_SYMBOL_SIDECAR_FAILED: ${(executed.stderr || executed.stdout || executed.error || 'unknown failure').trim().slice(0, 2_000)}`);
+  }
+  const response = JSON.parse(executed.stdout) as SourceSymbolsSidecarResponse;
+  if (response.schemaVersion !== 1 || !Array.isArray(response.symbols)) {
+    throw new Error('TYPESCRIPT_SOURCE_SYMBOL_SIDECAR_RESPONSE_INVALID');
+  }
+  return response.symbols;
+}
+
+export function navigateTypeScriptInSidecar(
+  repoRoot: string,
+  requests: SemanticNavigationRequest[],
+  access: SemanticNavigationAccess,
+): SemanticNavigationOutcome[] {
+  if (!access.readPolicy) {
+    return failedOutcomes(requests, 'SEMANTIC_READ_POLICY_REQUIRED', 'TypeScript semantic navigation requires a serializable repository read policy.');
+  }
+
+  let command: ReturnType<typeof resolveTypeScriptNavigationSidecarCommand>;
+  try {
+    command = resolveTypeScriptNavigationSidecarCommand();
+  } catch (error) {
+    return failedOutcomes(requests, 'TYPESCRIPT_NAVIGATION_SIDECAR_UNAVAILABLE', error instanceof Error ? error.message : String(error));
+  }
+
+  const envelope = {
+    schemaVersion: 1,
+    operation: 'navigation',
+    repoRoot: resolve(repoRoot),
+    requests,
+    access: {
+      cacheScope: access.cacheScope,
+      ...(access.sourceIdentity ? { sourceIdentity: access.sourceIdentity } : {}),
+      profile: access.profile,
+      readPolicy: access.readPolicy,
+    },
+  };
+  const executed = runProcess(command.executable, command.args, {
+    cwd: command.cwd ?? repoRoot,
+    input: JSON.stringify(envelope),
+    timeoutMs: TYPESCRIPT_NAVIGATION_TIMEOUT_MS,
+    maxOutputBytes: TYPESCRIPT_NAVIGATION_MAX_OUTPUT_BYTES,
+  });
+  if (!executed.ok) {
+    const detail = (executed.stderr || executed.stdout || executed.error || 'TypeScript navigation sidecar failed').trim();
+    return failedOutcomes(requests, 'TYPESCRIPT_NAVIGATION_SIDECAR_FAILED', detail.slice(0, 2_000));
+  }
+
+  try {
+    const response = JSON.parse(executed.stdout) as SidecarResponse;
+    if (response.schemaVersion !== 1 || !Array.isArray(response.outcomes) || response.outcomes.length !== requests.length) {
+      throw new Error('invalid sidecar response shape');
+    }
+    return response.outcomes;
+  } catch (error) {
+    return failedOutcomes(requests, 'TYPESCRIPT_NAVIGATION_SIDECAR_RESPONSE_INVALID', error instanceof Error ? error.message : String(error));
+  }
+}