@moretea-labs/forge 1.8.0 → 1.8.2

package/src/cli/commands/setup-profile.ts

@@ -8,6 +8,7 @@ import { dirname, join, resolve } from 'path';
 import { openAiSecureTunnelStatusArgs, parseOpenAiSecureTunnelRuntimeStatus, tunnelRuntimeProfileTargetsEndpoint } from '../../../adapters/mcp/tunnels/openai-secure-tunnel';
 import { discoverExecutable, type ExecutableDiscoveryResult } from '../../runtime/platform/executable-discovery';
 import { resolvePlatformServiceManager, type PlatformServiceManagerKind } from '../../runtime/platform/service-manager';
+import { deriveRuntimeDeploymentTopology, type RuntimeDeploymentTopology } from '../../runtime/root/deployment-topology';
 
 export type SetupControllerKind = 'chatgpt' | 'codex' | 'claude' | 'mcp';
 export type SetupTunnelProvider = 'auto' | 'openai' | 'cloudflare' | 'tailscale' | 'existing' | 'none';
@@ -187,6 +188,13 @@ export function setupNeedsRemoteAccess(profile: SetupProfile | undefined): boole
   return Boolean(profile?.controllers.some((entry) => entry === 'chatgpt' || entry === 'mcp'));
 }
 
+export function runtimeDeploymentTopologyForSetupProfile(profile: SetupProfile): RuntimeDeploymentTopology {
+  return deriveRuntimeDeploymentTopology({
+    controllers: profile.controllers,
+    capabilityIntents: profile.capabilityIntents,
+  });
+}
+
 export type SetupConnectorAuthMode = 'oauth' | 'none';
 
 export function setupConnectorAuthMode(profile: SetupProfile | undefined): SetupConnectorAuthMode {

package/src/cli/controller/check-runner.ts

@@ -280,8 +280,19 @@ function inferredPackageCheckEffects(name: string): ControllerCheckEffects | und
     // and persist only content-bound receipts/caches outside repository source.
     return { reads: ['.'], cache: 'write', temp: 'isolated', git: 'read' };
   }
-  const staticAnalysis = /(?:^|:)(?:type|typecheck|lint|format:check|runtime-architecture|mcp-compatibility|forge-runtime)$/.test(normalized);
-  if (staticAnalysis) return { reads: ['.'], cache: 'write' };
+  if (normalized === 'check:type' || normalized === 'check:runtime-architecture') {
+    // These canonical gates are source readers: TypeScript runs with --noEmit,
+    // while runtime-architecture only inspects source/AST structure. Neither
+    // owns the shared repository build cache.
+    return { reads: ['.'] };
+  }
+  if (normalized === 'check:architecture-sync') {
+    // Architecture sync runs the queue in --check mode and inspects Git state.
+    // Its scratch space is check-local; it never mutates repository source.
+    return { reads: ['.'], temp: 'isolated', git: 'read' };
+  }
+  const cachedStaticAnalysis = /(?:^|:)(?:typecheck|lint|format:check|mcp-compatibility|forge-runtime)$/.test(normalized);
+  if (cachedStaticAnalysis) return { reads: ['.'], cache: 'write' };
   const isolatedReadOnlyCheck = /(?:^|:)(?:quality-harness|evaluation-framework|background-check-overlap|typescript-navigation|check-scheduling|bootstrap-files)$/.test(normalized);
   if (isolatedReadOnlyCheck) return { reads: ['.'], temp: 'isolated', git: 'read' };
   const browserLive = /(?:^|:)browser-live$/.test(normalized);

package/src/cli/controller/completion-backlog.ts

@@ -145,11 +145,11 @@ function classifyTask(repoRoot: string, issue: ControllerIssue, task: Controller
   }
 
   if (run && FINISHABLE_RUN_STATUSES.has(run.status)) {
-    if (policy.requiresHumanAcceptance) {
+    if (task.acceptanceCriteria.length > 0) {
       return {
         ...base,
         action: 'needs_human_review',
-        reason: `${policy.executionClass} requires explicit review before finishing ${run.runId}.`,
+        reason: `Task declares acceptance criteria that require an explicit acceptance decision before finishing ${run.runId}.`,
         canAutoFinish: false,
         suggestedDecision: 'approve_and_finish',
       };
@@ -157,7 +157,7 @@ function classifyTask(repoRoot: string, issue: ControllerIssue, task: Controller
     return {
       ...base,
       action: 'auto_finish',
-      reason: `Run ${run.runId} is ${run.status} and policy allows automatic finish.`,
+      reason: `Run ${run.runId} is ${run.status} and the Task declares no semantic acceptance criteria, so automatic finish may proceed.`,
       canAutoFinish: true,
       suggestedDecision: 'auto',
     };

package/src/cli/controller/completion-orchestrator.ts

@@ -6,12 +6,12 @@ import { getAgentJob, markAgentJobClosure, markAgentJobReviewedCompletion, recor
 import type { AgentJobMeta } from '../agent-jobs/types';
 import { cleanupIntegratedWorktree, cleanupNoChangeWorktree, integrateAgentJob, IntegrationReviewRequiredError, taskRunDiff } from '../agent-jobs/integration';
 import { finalizeEditSession, getEditSession, revalidateEditSessionOwnership, rollbackEditSession, verifyEditSession } from '../editing/edit-session';
-import { getMcpPolicy } from '../mcp/policy';
+import { getMcpPolicy } from '../../../adapters/mcp/policy';
 import { resolveRepoPreferredControllerHome } from '../repositories/controller-home';
 import { withControllerLock } from '../repositories/locks';
 import { listActiveLeases } from '../../runtime/resources/leases/store';
 import { acceptVerifiedTask, getIssue, projectIssueEffectiveView, recordTaskVerification, updateTask } from './issue-store';
-import { cleanupEvidenceResourceBlockers, completionEvidenceComplete, taskExecutionPolicy } from './execution-policy';
+import { cleanupEvidenceResourceBlockers, completionEvidenceComplete } from './execution-policy';
 import { currentCompletionTarget, resolveCompletionTargetBranch } from './completion-target';
 import { runControllerCheck } from './check-runner';
 import type { CleanupEvidence, ControllerIssue, ControllerTask, IntegrationEvidence, TaskCommandEvidence, TaskVerification } from './types';
@@ -183,7 +183,6 @@ function verificationForRun(
   reviewer: string,
   evidence: { integrationEvidence?: IntegrationEvidence; cleanupEvidence?: CleanupEvidence; completionReceipt?: CompletionReceipt; acceptanceConfirmed?: boolean } = {},
 ): TaskVerification {
-  const policy = taskExecutionPolicy(task);
   const acceptanceResults = task.acceptanceCriteria.map((criterion) => evidence.acceptanceConfirmed
     ? {
       criterion,
@@ -204,8 +203,7 @@ function verificationForRun(
     integratedRevision: evidence.integrationEvidence?.targetRevision,
     reviewedDiffHash: hashArtifact(repoRoot, run.diffArtifactPath),
     reviewer,
-    checkResults: policy.autoRunDeclaredChecks
-      ? task.checks.map((checkId) => {
+    checkResults: task.checks.map((checkId) => {
         try {
           const result = runControllerCheck(repoRoot, checkId);
           return {
@@ -218,8 +216,7 @@ function verificationForRun(
         } catch (error) {
           return { checkId, ok: false, summary: error instanceof Error ? error.message : String(error) };
         }
-      })
-      : [],
+      }),
     commandEvidence: commandEvidenceForRun(run),
     acceptanceResults,
     verifiedAt: nowIso(),
@@ -233,8 +230,7 @@ function result(repoRoot: string, input: Omit<FinishTaskRunResult, 'issue'>): Fi
 }
 
 function canAutoFinish(task: ControllerTask): boolean {
-  const policy = taskExecutionPolicy(task);
-  return policy.autoCompleteAfterSuccessfulRun && !policy.requiresHumanAcceptance;
+  return task.acceptanceCriteria.length === 0;
 }
 
 function verifyAndMaybeAccept(input: {
@@ -247,16 +243,7 @@ function verifyAndMaybeAccept(input: {
   allowCompletion?: boolean;
 }): { issue: ControllerIssue; taskStatus: string } {
   const { repoRoot, run, task, decision, reviewer } = input;
-  const policy = taskExecutionPolicy(task);
   const allowHumanAcceptance = decision === 'approve_and_finish';
-  if (policy.requiresHumanAcceptance && !allowHumanAcceptance) {
-    updateTask(repoRoot, run.issueId, run.taskId, {
-      status: task.status === 'verified' ? 'verified' : task.status,
-      note: input.note ?? `Run ${run.runId} is ready but ${policy.executionClass} requires an explicit review decision.`,
-    });
-    const waiting = getIssue(repoRoot, run.issueId);
-    return { issue: waiting, taskStatus: taskForRun(waiting, run.taskId).status };
-  }
 
   const current = getIssue(repoRoot, run.issueId);
   const currentTask = taskForRun(current, run.taskId);
@@ -438,19 +425,6 @@ function finishEditSessionUnlocked(repoRoot: string, options: FinishEditSessionO
     });
   }
 
-  const policy = taskExecutionPolicy(task);
-  if (policy.requiresHumanAcceptance && decision !== 'approve_and_finish') {
-    return editResult(repoRoot, {
-      action: 'needs_decision',
-      sessionId: initialSession.sessionId,
-      issueId: issue.id,
-      taskId: task.id,
-      decision,
-      taskStatus: task.status,
-      reason: `${policy.executionClass} requires approve_and_finish, request_changes, or discard.`,
-    });
-  }
-
   const completionTarget = currentCompletionTarget(repoRoot);
   if (!completionTarget.onTargetBranch) {
     return editResult(repoRoot, {
@@ -1165,19 +1139,6 @@ function finishTaskRunUnlocked(repoRoot: string, options: FinishTaskRunOptions):
     });
   }
 
-  const policy = taskExecutionPolicy(task);
-  if (policy.requiresHumanAcceptance && decision !== 'approve_and_finish') {
-    return result(repoRoot, {
-      action: 'needs_decision',
-      runId: run.runId,
-      issueId: issue.id,
-      taskId: task.id,
-      decision,
-      taskStatus: task.status,
-      reason: `${policy.executionClass} requires approve_and_finish, request_changes, or discard.`,
-    });
-  }
-
   const ownedAutoFinalization = run.status === 'running'
     && run.autoIntegrate === true
     && run.executionMode === 'worktree'

package/src/cli/controller/completion-target.ts

@@ -1,8 +1,4 @@
-import { realpathSync, statSync } from 'fs';
 import { spawnSync } from 'child_process';
-import { join } from 'path';
-import { resolveRepoPreferredControllerHome, resolveControllerHome } from '../repositories/controller-home';
-import { listRepositories } from '../repositories/registry';
 
 function gitText(repoRoot: string, args: string[]): string {
   const result = spawnSync('git', args, { cwd: repoRoot, encoding: 'utf-8' });
@@ -10,75 +6,10 @@ function gitText(repoRoot: string, args: string[]): string {
   return typeof result.stdout === 'string' ? result.stdout.trim() : '';
 }
 
-function canonical(path: string): string {
-  try { return realpathSync(path); }
-  catch (_error) { return path; }
-}
-
-interface TargetBranchCacheEntry {
-  branch: string;
-  registryMtimeMs: number;
-  expiresAt: number;
-}
-
-/**
- * Short-lived cache: invalidated by registry mtime or 30s TTL.
- *
- * Policy (do not rewrite without explicit design change):
- * - registry mtime 变化时立即失效；
- * - 未检测到 mtime 变化时，defaultBranch 变更最多存在 30 秒可见延迟。
- * - Cache keys include controllerHome + canonical repo root (no cross-repo bleed).
- * - Registry unavailable → Git fallback (origin/HEAD, main/master, current branch).
- */
-const targetBranchCache = new Map<string, TargetBranchCacheEntry>();
-const TARGET_BRANCH_TTL_MS = 30_000;
-
-function registryMtimeMs(controllerHome: string): number {
-  try {
-    return statSync(join(resolveControllerHome(controllerHome), 'repositories.json')).mtimeMs;
-  } catch {
-    return 0;
-  }
-}
-
-export function clearCompletionTargetCache(): void {
-  targetBranchCache.clear();
-}
-
 export function resolveCompletionTargetBranch(repoRoot: string): string {
-  const root = canonical(repoRoot);
-  try {
-    const home = resolveRepoPreferredControllerHome(repoRoot);
-    const mtime = registryMtimeMs(home);
-    const cacheKey = `${home}\0${root}`;
-    const cached = targetBranchCache.get(cacheKey);
-    const now = Date.now();
-    if (cached && cached.registryMtimeMs === mtime && cached.expiresAt > now) {
-      return cached.branch;
-    }
-    const registered = listRepositories(home, { includeRemoved: true }).find((record) => {
-      if (canonical(record.canonicalRoot) === root || canonical(record.localRoot) === root) return true;
-      return record.checkouts.some((checkout) => canonical(checkout.canonicalRoot) === root || canonical(checkout.localRoot) === root);
-    });
-    if (registered?.defaultBranch?.trim()) {
-      const branch = registered.defaultBranch.trim();
-      targetBranchCache.set(cacheKey, {
-        branch,
-        registryMtimeMs: mtime,
-        expiresAt: now + TARGET_BRANCH_TTL_MS,
-      });
-      return branch;
-    }
-  } catch (_error) {
-    // Temporary test repositories and unregistered clones fall through to Git discovery.
-  }
-
-  const remoteHead = gitText(repoRoot, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']);
-  if (remoteHead.startsWith('origin/')) return remoteHead.slice('origin/'.length);
-  for (const candidate of ['main', 'master']) {
-    if (gitText(repoRoot, ['show-ref', '--verify', '--hash', `refs/heads/${candidate}`])) return candidate;
-  }
-  return gitText(repoRoot, ['branch', '--show-current']) || 'main';
+  const branch = gitText(repoRoot, ['branch', '--show-current']);
+  if (!branch) throw new Error('integration target must be an attached branch');
+  return branch;
 }
 
 export function currentCompletionTarget(repoRoot: string): {

package/src/cli/controller/composite-operations.ts

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'fs';
 import { join } from 'path';
 import { createHash } from 'crypto';
 import { runProcess } from '../../effects/process-runner';
-import { resolveMcpRepoRoot } from '../mcp/repo';
+import { resolveMcpRepoRoot } from '../../../adapters/mcp/repo';
 import { listControllerChecks, runControllerCheck } from './check-runner';
 import {
   compositeFailed,

package/src/cli/controller/context/instruction-context.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from 'fs';
 import { posix, resolve } from 'path';
-import type { McpPolicy } from '../../mcp/types';
+import type { McpPolicy } from '../../../../adapters/mcp/types';
 import { readableFile } from './known-paths';
 
 const CONTRACT_NAMES = ['AGENTS.md', 'CLAUDE.md'] as const;

package/src/cli/controller/context/known-paths.ts

@@ -1,6 +1,6 @@
 import { existsSync, lstatSync, readdirSync, statSync } from 'fs';
-import { globMatches, resolveMcpPath } from '../../mcp/paths';
-import type { McpPolicy } from '../../mcp/types';
+import { globMatches, resolveMcpPath } from '../../../../adapters/mcp/paths';
+import type { McpPolicy } from '../../../../adapters/mcp/types';
 
 export function looksLikeGlob(path: string): boolean { return /[*?{[]/.test(path); }
 export function coveredByGlob(path: string, globs: string[]): boolean {

package/src/cli/controller/context/query-planning.ts

@@ -1,8 +1,8 @@
 import type { ControllerContextImpactDomain, ControllerContextRetrievalMode } from './types';
 
 export const DEFAULT_MAX_FILES = 8;
-export const DEFAULT_MAX_SNIPPETS = 20;
-export const DEFAULT_MAX_CHARS_PER_SNIPPET = 8000;
+export const DEFAULT_MAX_SNIPPETS = 12;
+export const DEFAULT_MAX_CHARS_PER_SNIPPET = 1800;
 export const DEFAULT_SEARCH_EXCLUDE_GLOBS = [
   '.git/**', '_ops/**', '.forge/**', '.ai/harness/**', 'node_modules/**', 'dist/**', 'coverage/**', '**/*.bak',
 ] as const;
@@ -47,13 +47,20 @@ export function pathNoisePenalty(path: string, intent: string, retrievalMode: Co
 export function textTokens(value: string): string[] {
   const split = value.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^\p{L}\p{N}_./:-]+/u)
     .map((entry) => entry.trim()).filter(Boolean);
-  return Array.from(new Set(split
+  // Preserve full code needles before their broad camel-case fragments.
+  return Array.from(new Set([...codeShapedAnchors(value), ...split]
     .map((entry) => entry.replace(/^[\'"`]+|[\'"`]+$/g, ''))
     .filter((entry) => entry.length >= 3)
     .filter((entry) => !STOPWORDS.has(entry.toLowerCase()))
     .filter((entry) => !/^\d+$/.test(entry)))).slice(0, 12);
 }
 
+/** Split explicit multi-symbol input into independent exact needles before search. */
+export function explicitCodeQueries(searchTerms: readonly string[] | undefined): string[] {
+  // Camel-case fragments are hints, not separately mandatory matches.
+  return Array.from(new Set((searchTerms ?? []).flatMap(codeShapedAnchors))).slice(0, 4);
+}
+
 /** A caller-supplied symbol or path is an exact retrieval needle, not a broad hint. */
 export function isCodeShapedTerm(value: string): boolean {
   const term = value.trim();
@@ -77,7 +84,7 @@ function codeShapedAnchors(value: string): string[] {
 }
 
 /**
- * CodeGraph's semantic query cost grows materially with long natural-language
+ * Structural providers' query cost grows materially with long natural-language
  * prompts. Keep short intents exact, but compact long intents around concrete
  * code anchors plus bounded semantic tokens. This affects only structural
  * discovery; lexical search and raw-source retrieval still consume the full

package/src/cli/controller/context/rule-resolution.ts

@@ -1,7 +1,7 @@
 import { closeSync, openSync, readSync, statSync } from 'fs';
 import { extname, resolve } from 'path';
-import { globMatches } from '../../mcp/paths';
-import type { McpPolicy } from '../../mcp/types';
+import { globMatches } from '../../../../adapters/mcp/paths';
+import type { McpPolicy } from '../../../../adapters/mcp/types';
 import { readableFile } from './known-paths';
 
 export const GOVERNANCE_RULES_PATH = '.ai/context/governance-rules.json';

package/src/cli/controller/context/source-materializer.ts

@@ -1,6 +1,6 @@
-import ts from 'typescript';
-import type { McpPolicy } from '../../mcp/types';
-import { redactMcpText } from '../../mcp/redaction';
+import type { McpPolicy } from '../../../../adapters/mcp/types';
+import { extractTypeScriptSourceSymbolsInSidecar } from '../../../runtime/context/typescript-navigation-process';
+import { redactMcpText } from '../../../../adapters/mcp/redaction';
 import { readRepositoryRange, type RepositoryReadSession } from '../../repository/inspector';
 
 const DEFAULT_CONTEXT_BEFORE = 12;
@@ -46,16 +46,8 @@ interface SymbolRange {
   enclosing?: string;
 }
 
-interface IndexedDeclaration {
-  node: ts.Node;
-  kind: string;
-  fullStart: number;
-  end: number;
-}
-
 interface SourceSymbolIndex {
-  sourceFile: ts.SourceFile;
-  declarations: IndexedDeclaration[];
+  declarations: SymbolRange[];
 }
 
 const SOURCE_SYMBOL_INDEX_CACHE_MAX_ENTRIES = 32;
@@ -77,11 +69,6 @@ export function clearSourceSymbolIndexCacheForTest(): void {
   sourceSymbolIndexCacheMisses = 0;
 }
 
-function boundedContent(content: string, maxChars: number): { content: string; truncated: boolean } {
-  if (content.length <= maxChars) return { content, truncated: false };
-  return { content: `${content.slice(0, maxChars)}\n... <snippet truncated>`, truncated: true };
-}
-
 function plainSource(numbered: string): string {
   return numbered
     .split(/\r?\n/)
@@ -107,70 +94,13 @@ function mergeHitLines(lines: number[]): number[] {
   return merged;
 }
 
-function scriptKind(path: string): ts.ScriptKind | undefined {
-  if (/\.tsx$/i.test(path)) return ts.ScriptKind.TSX;
-  if (/\.jsx$/i.test(path)) return ts.ScriptKind.JSX;
-  if (/\.(?:mts|cts|ts)$/i.test(path)) return ts.ScriptKind.TS;
-  if (/\.(?:mjs|cjs|js)$/i.test(path)) return ts.ScriptKind.JS;
-  return undefined;
-}
-
-function declarationName(node: ts.Node): string | undefined {
-  const named = node as ts.Node & { name?: ts.Node };
-  if (!named.name) return undefined;
-  return named.name.getText().slice(0, 200);
-}
-
-function declarationKind(node: ts.Node): string | undefined {
-  if (ts.isFunctionDeclaration(node)) return 'function';
-  if (ts.isMethodDeclaration(node)) return 'method';
-  if (ts.isConstructorDeclaration(node)) return 'constructor';
-  if (ts.isGetAccessorDeclaration(node)) return 'getter';
-  if (ts.isSetAccessorDeclaration(node)) return 'setter';
-  if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) return 'class';
-  if (ts.isInterfaceDeclaration(node)) return 'interface';
-  if (ts.isTypeAliasDeclaration(node)) return 'type';
-  if (ts.isEnumDeclaration(node)) return 'enum';
-  if (ts.isModuleDeclaration(node)) return 'module';
-  if (ts.isVariableStatement(node) && node.declarationList.declarations.some((declaration) =>
-    declaration.initializer && (ts.isArrowFunction(declaration.initializer) || ts.isFunctionExpression(declaration.initializer)))) return 'function-variable';
-  return undefined;
-}
-
-function enclosingName(node: ts.Node): string | undefined {
-  let current = node.parent;
-  while (current) {
-    if (ts.isClassDeclaration(current) || ts.isClassExpression(current) || ts.isInterfaceDeclaration(current) || ts.isModuleDeclaration(current)) {
-      const kind = declarationKind(current) ?? 'container';
-      const name = declarationName(current);
-      return name ? `${kind}:${name}` : kind;
-    }
-    current = current.parent;
-  }
-  return undefined;
-}
-
-function buildSourceSymbolIndex(path: string, source: string, kind: ts.ScriptKind): SourceSymbolIndex {
-  const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, kind);
-  const declarations: IndexedDeclaration[] = [];
-  const visit = (node: ts.Node): void => {
-    const candidateKind = declarationKind(node);
-    if (candidateKind) {
-      declarations.push({
-        node,
-        kind: candidateKind,
-        fullStart: node.getFullStart(),
-        end: node.end,
-      });
-    }
-    ts.forEachChild(node, visit);
-  };
-  visit(sourceFile);
-  return { sourceFile, declarations };
+function sourceSyntaxKind(path: string): string | undefined {
+  const match = path.toLowerCase().match(/\.(tsx|jsx|mts|cts|ts|mjs|cjs|js)$/);
+  return match?.[1];
 }
 
 function cachedSourceSymbolIndex(path: string, fileSha: string, numberedSource: string): SourceSymbolIndex | undefined {
-  const kind = scriptKind(path);
+  const kind = sourceSyntaxKind(path);
   if (kind === undefined) return undefined;
   const key = `${kind}:${fileSha}`;
   const cached = sourceSymbolIndexCache.get(key);
@@ -182,7 +112,9 @@ function cachedSourceSymbolIndex(path: string, fileSha: string, numberedSource:
   }
 
   sourceSymbolIndexCacheMisses += 1;
-  const built = buildSourceSymbolIndex(path, plainSource(numberedSource), kind);
+  const built: SourceSymbolIndex = {
+    declarations: extractTypeScriptSourceSymbolsInSidecar(path, plainSource(numberedSource)),
+  };
   sourceSymbolIndexCache.set(key, built);
   while (sourceSymbolIndexCache.size > SOURCE_SYMBOL_INDEX_CACHE_MAX_ENTRIES) {
     const oldest = sourceSymbolIndexCache.keys().next().value as string | undefined;
@@ -194,22 +126,13 @@ function cachedSourceSymbolIndex(path: string, fileSha: string, numberedSource:
 
 function symbolAtLine(index: SourceSymbolIndex | undefined, line: number): SymbolRange | undefined {
   if (!index) return undefined;
-  const { sourceFile, declarations } = index;
-  const targetLine = Math.min(Math.max(1, line), sourceFile.getLineAndCharacterOfPosition(sourceFile.end).line + 1);
-  const position = sourceFile.getPositionOfLineAndCharacter(targetLine - 1, 0);
-  let selected: IndexedDeclaration | undefined;
-  for (const candidate of declarations) {
-    if (candidate.fullStart > position || candidate.end < position) continue;
-    if (!selected || (candidate.end - candidate.fullStart) < (selected.end - selected.fullStart)) selected = candidate;
+  const targetLine = Math.max(1, line);
+  let selected: SymbolRange | undefined;
+  for (const candidate of index.declarations) {
+    if (candidate.startLine > targetLine || candidate.endLine < targetLine) continue;
+    if (!selected || (candidate.endLine - candidate.startLine) < (selected.endLine - selected.startLine)) selected = candidate;
   }
-  if (!selected) return undefined;
-  return {
-    startLine: sourceFile.getLineAndCharacterOfPosition(selected.node.getStart(sourceFile)).line + 1,
-    endLine: sourceFile.getLineAndCharacterOfPosition(selected.node.end).line + 1,
-    kind: selected.kind,
-    name: declarationName(selected.node),
-    enclosing: enclosingName(selected.node),
-  };
+  return selected;
 }
 
 function materializedSnippet(
@@ -219,18 +142,42 @@ function materializedSnippet(
   materialization: SourceMaterializationKind,
   symbol?: SymbolRange,
 ): MaterializedSourceSnippet {
-  const numbered = sliceNumbered(full.content, range.startLine, range.endLine);
-  const redacted = redactMcpText(numbered);
-  const bounded = boundedContent(redacted.text, options.maxCharsPerSnippet);
+  let low = range.startLine;
+  let high = range.endLine;
+  let exactEndLine = range.startLine - 1;
+  let exactContent = '';
+  let exactRedactions: Array<{ type: string; count: number }> = [];
+  while (low <= high) {
+    const candidateEndLine = Math.floor((low + high) / 2);
+    const redacted = redactMcpText(sliceNumbered(full.content, range.startLine, candidateEndLine));
+    if (redacted.text.length <= options.maxCharsPerSnippet) {
+      exactEndLine = candidateEndLine;
+      exactContent = redacted.text;
+      exactRedactions = redacted.redactions;
+      low = candidateEndLine + 1;
+    } else {
+      high = candidateEndLine - 1;
+    }
+  }
+  // Source evidence is line-addressed. Never character-cut content while still
+  // reporting the original endLine. A single unusually long line stays intact
+  // so the reported source range remains truthful; outer response budgets remain
+  // the hard transport fence.
+  if (exactEndLine < range.startLine) {
+    const redacted = redactMcpText(sliceNumbered(full.content, range.startLine, range.startLine));
+    exactEndLine = range.startLine;
+    exactContent = redacted.text;
+    exactRedactions = redacted.redactions;
+  }
   return {
     path: full.path,
     startLine: range.startLine,
-    endLine: range.endLine,
+    endLine: exactEndLine,
     totalLines: full.totalLines,
     sha256: full.sha256,
-    content: bounded.content,
-    truncated: bounded.truncated,
-    redactions: redacted.redactions,
+    content: exactContent,
+    truncated: exactEndLine < range.endLine,
+    redactions: exactRedactions,
     reason: options.reasons.join(', '),
     cacheHit: full.cacheHit,
     materialization,
@@ -238,6 +185,33 @@ function materializedSnippet(
   };
 }
 
+function materializedRange(
+  full: ReturnType<typeof readRepositoryRange>,
+  range: { startLine: number; endLine: number },
+  options: MaterializeSourceOptions,
+  materialization: SourceMaterializationKind,
+  maxSnippets: number,
+  symbol?: SymbolRange,
+): MaterializedSourceSnippet[] {
+  const snippets: MaterializedSourceSnippet[] = [];
+  let startLine = range.startLine;
+  while (startLine <= range.endLine && snippets.length < maxSnippets) {
+    const snippet = materializedSnippet(
+      full,
+      { startLine, endLine: range.endLine },
+      options,
+      materialization,
+      symbol,
+    );
+    snippets.push({ ...snippet, truncated: false });
+    startLine = snippet.endLine + 1;
+  }
+  if (startLine <= range.endLine && snippets.length > 0) {
+    snippets[snippets.length - 1] = { ...snippets[snippets.length - 1]!, truncated: true };
+  }
+  return snippets;
+}
+
 /**
  * Materialize current source in semantic units. Complete small files and
  * complete TypeScript/JavaScript declarations win; a fixed line window is the
@@ -272,7 +246,14 @@ export function materializeSource(options: MaterializeSourceOptions): Materializ
     const key = `${range.startLine}:${range.endLine}`;
     if (seen.has(key)) continue;
     seen.add(key);
-    snippets.push(materializedSnippet(full, range, options, symbol ? 'symbol' : 'line_window', symbol));
+    snippets.push(...materializedRange(
+      full,
+      range,
+      options,
+      symbol ? 'symbol' : 'line_window',
+      options.maxSnippets - snippets.length,
+      symbol,
+    ));
   }
   return snippets;
 }