@moretea-labs/forge 1.6.0 → 1.7.0

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

@@ -206,7 +206,7 @@ export function detectSetupPlatform(options: { platform?: NodeJS.Platform; arch?
 }
 
 
-function isLoopbackMcpEndpoint(value: string | undefined): boolean {
+function isLoopbackMcpEndpoint(value: string | undefined): value is string {
   if (!value) return false;
   try {
     const parsed = new URL(value);
@@ -220,6 +220,11 @@ function isLoopbackMcpEndpoint(value: string | undefined): boolean {
   }
 }
 
+function tunnelRuntimeProfileTargetsEndpoint(profilePath: string | undefined, endpoint: string): boolean {
+  if (!profilePath) return false;
+  try { return readFileSync(profilePath, 'utf8').includes(endpoint); } catch { return false; }
+}
+
 export interface ControllerGuidance {
   controller: SetupControllerKind;
   ready: boolean;
@@ -266,8 +271,8 @@ export function resolveControllerGuidance(
           controller,
           ready: false,
           title: controller === 'chatgpt' ? 'Configure the ChatGPT controller endpoint' : 'Configure the remote MCP controller endpoint',
-          detail: 'Create the user-level Forge OAuth/MCP configuration. This does not install Codex or Claude and does not require a repository.',
-          command: `forge mcp setup chatgpt --user-level${endpoint}`,
+          detail: 'Create or refresh the Forge OAuth/MCP configuration in the selected Controller Home. This does not install Codex or Claude and does not require a repository.',
+          command: `forge mcp setup chatgpt --user-level --controller-home ${JSON.stringify(controllerHome)}${endpoint}`,
         };
       }
       continue;
@@ -327,7 +332,7 @@ export function resolveRuntimeGuidance(
     ready: false,
     title: 'Install the user-level Forge Runtime',
     detail: 'Use the packaged Runtime path. It does not require a Git checkout, Bun compilation, CodeGraph, or Standalone Recovery.',
-    command: 'forge runtime service install-package',
+    command: `forge runtime service install-package --controller-home ${JSON.stringify(controllerHome)}`,
   };
 }
 
@@ -364,48 +369,53 @@ export function resolveTunnelGuidance(
         detail: 'Install the supported tunnel-client binary from OpenAI Platform Tunnels or the official openai/tunnel-client release. The runtime API key remains an environment/file reference owned by tunnel-client; Forge does not store it.',
       };
     }
+    const localConfig = loadMcpServiceLocalConfig(resolveControllerHome(options.controllerHome));
+    const localEndpoint = localConfig?.chatgpt?.localEndpoint;
+    if (!isLoopbackMcpEndpoint(localEndpoint)) {
+      return {
+        provider, ready: false, title: 'Prepare the local ChatGPT OAuth endpoint',
+        detail: 'Secure Tunnel must terminate at Forge’s loopback OAuth Gateway, not the bearer-only Canonical Runtime. Refresh the user-level ChatGPT MCP configuration first.',
+        command: `forge mcp setup chatgpt --user-level --controller-home ${JSON.stringify(resolveControllerHome(options.controllerHome))}`,
+      };
+    }
     const preferredAlias = 'forge';
-    const aliases = [preferredAlias];
+    const configuredAliases: string[] = [];
     const listed = spawnSync('tunnel-client', ['runtimes', 'list', '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000, env: options.env ?? process.env });
     if (listed.status === 0) {
       try {
         const value = JSON.parse(listed.stdout || '{}') as { aliases?: Array<{ alias?: string; tunnel_id?: string }> };
         for (const entry of value.aliases ?? []) {
-          if (entry.tunnel_id === profile.tunnel.tunnelId && entry.alias) aliases.push(entry.alias);
+          if (entry.tunnel_id === profile.tunnel.tunnelId && entry.alias) configuredAliases.push(entry.alias);
         }
       } catch {
         // Older clients may not expose local aliases as JSON. Keep the preferred alias fallback.
       }
     }
-    for (const alias of Array.from(new Set(aliases))) {
+    const aliases = Array.from(new Set([...configuredAliases, preferredAlias]));
+    for (const alias of aliases) {
       const status = spawnSync('tunnel-client', ['runtimes', 'status', alias, '--json'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 15_000, env: options.env ?? process.env });
       if (status.status !== 0) continue;
       try {
-        const value = JSON.parse(status.stdout || '{}') as { process_running?: boolean; healthy?: boolean; ready?: boolean; tunnel_id?: string };
+        const value = JSON.parse(status.stdout || '{}') as { process_running?: boolean; healthy?: boolean; ready?: boolean; tunnel_id?: string; profile_path?: string };
         if (value.process_running === true && value.healthy === true && value.ready === true
-          && (!value.tunnel_id || value.tunnel_id === profile.tunnel.tunnelId)) {
+          && value.tunnel_id === profile.tunnel.tunnelId
+          && tunnelRuntimeProfileTargetsEndpoint(value.profile_path, localEndpoint)) {
           return {
             provider, ready: true, title: 'OpenAI Secure MCP Tunnel',
-            detail: `Managed runtime ${alias} is running, healthy, and ready for ${profile.tunnel.tunnelId}.`,
+            detail: `Managed runtime ${alias} is running, healthy, and bound to ${profile.tunnel.tunnelId} -> ${localEndpoint}.`,
           };
         }
       } catch {
         // Treat malformed or older status output as not-ready instead of claiming success.
       }
     }
-    const alias = preferredAlias;
-    const localConfig = loadMcpServiceLocalConfig(resolveControllerHome(options.controllerHome));
-    const localEndpoint = localConfig?.chatgpt?.localEndpoint;
-    if (!isLoopbackMcpEndpoint(localEndpoint)) {
-      return {
-        provider, ready: false, title: 'Prepare the local ChatGPT OAuth endpoint',
-        detail: 'Secure Tunnel must terminate at Forge’s loopback OAuth Gateway, not the bearer-only Canonical Runtime. Refresh the user-level ChatGPT MCP configuration first.',
-        command: 'forge mcp setup chatgpt --user-level',
-      };
-    }
+    // A stopped alias still owns its recorded tunnel identity. Reconnect that
+    // alias instead of repointing the conventional `forge` alias, which may
+    // legitimately refer to a different tunnel from an earlier setup.
+    const alias = configuredAliases[0] ?? preferredAlias;
     return {
       provider, ready: false, title: 'Connect OpenAI Secure MCP Tunnel',
-      detail: 'Create a supervised tunnel-client runtime and verify it with runtimes status. Keep the runtime API key in an environment or file reference owned by tunnel-client; Forge never reads or stores the key.',
+      detail: 'Create a supervised tunnel-client runtime and verify its tunnel id and MCP target with runtimes status. Keep the runtime API key in an environment or file reference owned by tunnel-client; Forge never reads or stores the key.',
       command: `tunnel-client runtimes connect --alias ${alias} --tunnel-id ${profile.tunnel.tunnelId} --runtime-api-key env:CONTROL_PLANE_API_KEY --mcp-server-url ${localEndpoint}`,
     };
   }

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

@@ -11,6 +11,7 @@ import { atomicWriteFileSync } from '../installer/shared';
 import { runBoundedChild } from '../../runtime/shared/bounded-child-supervisor';
 import { signalProcessTree } from '../../runtime/shared/process-tree';
 import { repositoryChildProcessEnvironment, resolveBunExecutable } from '../../runtime/shared/process-environment';
+import { materializeManagedWorkspaceCheckDependencies } from '../../runtime/execution/managed-workspace';
 
 export interface ControllerCheckEffects {
   /** Repository-relative read scopes. Use [\".\"] for the whole checkout. */
@@ -25,6 +26,18 @@ export interface ControllerCheckEffects {
   hostServices?: string[];
 }
 
+export type ControllerCheckCostClass = 'L0' | 'L1' | 'L2' | 'L3' | 'L4';
+export type ControllerCheckRiskFloor = 'readonly' | 'low' | 'medium' | 'high' | 'destructive';
+export type ControllerCheckPhase = 'pre_edit' | 'post_edit' | 'pre_finalize' | 'release';
+
+export interface ControllerCheckSelection {
+  /** Execution cost only; it does not lower severity or automatically run the check. */
+  costClass: ControllerCheckCostClass;
+  /** Lowest change-risk band where this check is normally useful when selected mechanically. */
+  riskFloor: ControllerCheckRiskFloor;
+  phases: ControllerCheckPhase[];
+}
+
 export interface ControllerCheck {
   id: string;
   description: string;
@@ -33,6 +46,8 @@ export interface ControllerCheck {
   timeoutMs: number;
   source: 'repo-config' | 'package-script';
   effects?: ControllerCheckEffects;
+  /** Selection/preflight metadata; intentionally excluded from physical execution identity. */
+  selection?: ControllerCheckSelection;
 }
 
 export interface ControllerCheckSnapshot extends ControllerCheck {
@@ -68,10 +83,12 @@ interface CheckConfig {
     cwd?: string;
     timeoutMs?: number;
     effects?: unknown;
+    selection?: unknown;
   }>;
 }
 
 const CHECK_CONFIG = '.forge/checks.json';
+const LEGACY_TRACKED_CHECK_CONFIG = '.repo-harness/checks.json';
 const CHECK_EVIDENCE_ROOT = '.ai/harness/checks/controller';
 const HEAVY_CHECK_LOCK = '.ai/harness/controller/heavy-check.lock';
 const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
@@ -180,15 +197,87 @@ function normalizeCheckEffects(repoRoot: string, value: unknown): ControllerChec
   };
 }
 
+const CHECK_COST_CLASSES = ['L0', 'L1', 'L2', 'L3', 'L4'] as const;
+const CHECK_RISK_FLOORS = ['readonly', 'low', 'medium', 'high', 'destructive'] as const;
+const CHECK_PHASES = ['pre_edit', 'post_edit', 'pre_finalize', 'release'] as const;
+
+function inferredCheckSelection(name: string): ControllerCheckSelection {
+  const normalized = name.trim().toLowerCase().replace(/^package:/, '');
+  if (/(?:^|:)(?:check:)?release$|full[-:]?regression/.test(normalized)) {
+    return { costClass: 'L4', riskFloor: 'high', phases: ['release'] };
+  }
+  if (/(?:^|:)(?:check:)?main$|(?:^|:)ci(?::|$)/.test(normalized)) {
+    return { costClass: 'L4', riskFloor: 'medium', phases: ['pre_finalize'] };
+  }
+  if (/(?:^|:)(?:browser-live|performance|journey)(?::|$)/.test(normalized)) {
+    return { costClass: 'L3', riskFloor: 'medium', phases: ['pre_finalize'] };
+  }
+  if (/(?:^|:)(?:integration|build)(?::|$)/.test(normalized) || normalized === 'test') {
+    return { costClass: 'L2', riskFloor: 'medium', phases: ['post_edit', 'pre_finalize'] };
+  }
+  if (/(?:^|:)(?:architecture-sync|check-scheduling|context-files|bootstrap-files|background-check-overlap)$/.test(normalized)) {
+    return { costClass: 'L0', riskFloor: 'low', phases: ['post_edit'] };
+  }
+  return { costClass: 'L1', riskFloor: 'low', phases: ['post_edit'] };
+}
+
+function normalizeCheckSelection(value: unknown, id: string): ControllerCheckSelection {
+  const fallback = inferredCheckSelection(id);
+  if (value === undefined) return fallback;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('check selection must be an object');
+  const raw = value as Record<string, unknown>;
+  const unsupported = Object.keys(raw).filter((key) => !['costClass', 'cost_class', 'riskFloor', 'risk_floor', 'phases'].includes(key));
+  if (unsupported.length > 0) throw new Error(`unsupported check selection field(s): ${unsupported.join(', ')}`);
+  const cost = raw.costClass ?? raw.cost_class;
+  const risk = raw.riskFloor ?? raw.risk_floor;
+  const phases = raw.phases;
+  if (cost !== undefined && (typeof cost !== 'string' || !CHECK_COST_CLASSES.includes(cost as ControllerCheckCostClass))) {
+    throw new Error(`check selection.costClass must be one of: ${CHECK_COST_CLASSES.join(', ')}`);
+  }
+  if (risk !== undefined && (typeof risk !== 'string' || !CHECK_RISK_FLOORS.includes(risk as ControllerCheckRiskFloor))) {
+    throw new Error(`check selection.riskFloor must be one of: ${CHECK_RISK_FLOORS.join(', ')}`);
+  }
+  if (phases !== undefined && (!Array.isArray(phases) || phases.length === 0 || phases.some((entry) => typeof entry !== 'string' || !CHECK_PHASES.includes(entry as ControllerCheckPhase)))) {
+    throw new Error(`check selection.phases must contain one or more of: ${CHECK_PHASES.join(', ')}`);
+  }
+  return {
+    costClass: (cost as ControllerCheckCostClass | undefined) ?? fallback.costClass,
+    riskFloor: (risk as ControllerCheckRiskFloor | undefined) ?? fallback.riskFloor,
+    phases: phases ? [...new Set(phases as ControllerCheckPhase[])] : fallback.phases,
+  };
+}
+
+export function controllerCheckSelection(check: Pick<ControllerCheck, 'id' | 'selection'>): ControllerCheckSelection {
+  return check.selection ?? inferredCheckSelection(check.id);
+}
+
 function inferredPackageCheckEffects(name: string): ControllerCheckEffects | undefined {
   const normalized = name.trim().toLowerCase();
   const staticAnalysis = /(?:^|:)(?:type|typecheck|lint|format:check|runtime-architecture|mcp-compatibility|forge-runtime)$/.test(normalized);
-  return staticAnalysis ? { reads: ['.'], cache: 'write' } : undefined;
+  if (staticAnalysis) 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);
+  if (browserLive) {
+    return {
+      reads: ['.'],
+      temp: 'isolated',
+      hostServices: ['browser-live'],
+    };
+  }
+  return undefined;
 }
 
 function configuredChecks(repoRoot: string): ControllerCheck[] {
-  const path = join(repoRoot, CHECK_CONFIG);
-  if (!existsSync(path)) return [];
+  // `.forge/` may intentionally be machine-local/ignored. Preserve it as the
+  // authoritative current location, but inherit the tracked legacy registry in
+  // isolated Git checkouts when the current file is absent. Never merge both:
+  // deterministic precedence prevents checkout-local definitions from being
+  // silently combined with portable repository policy.
+  const currentPath = join(repoRoot, CHECK_CONFIG);
+  const legacyPath = join(repoRoot, LEGACY_TRACKED_CHECK_CONFIG);
+  const path = existsSync(currentPath) ? currentPath : existsSync(legacyPath) ? legacyPath : undefined;
+  if (!path) return [];
   const config = JSON.parse(readFileSync(path, 'utf-8')) as CheckConfig;
   return Object.entries(config.checks ?? {}).flatMap(([id, value]) => {
     if (!Array.isArray(value.command) || value.command.length === 0 || value.command.some((part) => typeof part !== 'string' || part.length === 0)) return [];
@@ -200,6 +289,7 @@ function configuredChecks(repoRoot: string): ControllerCheck[] {
       timeoutMs: boundedTimeout(value.timeoutMs),
       source: 'repo-config' as const,
       effects: normalizeCheckEffects(repoRoot, value.effects),
+      selection: normalizeCheckSelection(value.selection, id),
     }];
   });
 }
@@ -223,6 +313,7 @@ function packageChecks(repoRoot: string): ControllerCheck[] {
       timeoutMs: packageScriptTimeoutMs(name),
       source: 'package-script' as const,
       effects: inferredPackageCheckEffects(name),
+      selection: inferredCheckSelection(name),
     }];
   });
 }
@@ -360,6 +451,7 @@ function validateControllerCheckSnapshot(repoRoot: string, snapshot: ControllerC
     timeoutMs: boundedTimeout(snapshot.timeoutMs),
     source: snapshot.source,
     effects: normalizeCheckEffects(repoRoot, snapshot.effects),
+    selection: normalizeCheckSelection(snapshot.selection, snapshot.id),
   };
 }
 
@@ -541,9 +633,15 @@ function readControllerCheckEvidenceByKey(repoRoot: string, id: string, cacheKey
   }
 }
 
+function prepareControllerCheckDependencies(repoRoot: string, check: ControllerCheck): void {
+  if (check.source !== 'package-script' || existsSync(join(repoRoot, 'node_modules'))) return;
+  materializeManagedWorkspaceCheckDependencies(repoRoot);
+}
+
 export function runControllerCheck(repoRoot: string, id: string, requestedTimeoutMs?: number, snapshot?: ControllerCheckSnapshot): ControllerCheckResult {
   const check = snapshot ? validateControllerCheckSnapshot(repoRoot, snapshot) : listControllerChecks(repoRoot).find((entry) => entry.id === id);
   if (!check || check.id !== id) throw new Error(`check not found: ${id}`);
+  prepareControllerCheckDependencies(repoRoot, check);
   const identity = controllerCheckExecutionIdentity(repoRoot, id, requestedTimeoutMs, snapshot);
   const timeoutMs = identity.timeoutMs;
   const revision = identity.revision;
@@ -877,6 +975,11 @@ export function runControllerCheckAsync(
     return Promise.reject(error);
   }
   if (!check || check.id !== id) return Promise.reject(new Error(`check not found: ${id}`));
+  try {
+    prepareControllerCheckDependencies(repoRoot, check);
+  } catch (error) {
+    return Promise.reject(error);
+  }
   const identity = controllerCheckExecutionIdentity(repoRoot, id, options.requestedTimeoutMs, options.snapshot);
   const timeoutMs = identity.timeoutMs;
   const revision = identity.revision;

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

@@ -124,7 +124,7 @@ export function compositeRunning(input: {
     keyOutput: boundKeyOutput(input.keyOutput ?? input.summary),
     evidenceRefs: input.evidenceRefs ?? [],
     retryable: false,
-    nextAction: input.nextAction ?? 'poll the same durable request id; do not resubmit',
+    nextAction: input.nextAction ?? 'Continue independent work; inspect this request only when its outcome can change the next decision. Do not resubmit or periodically poll.',
     details: input.details,
   };
 }

package/src/cli/controller/context/focus.ts

@@ -0,0 +1,51 @@
+import type { TaskLedgerTaskProjection } from '../task-ledger';
+import type { projectBoard } from '../issue-store';
+import type { buildControllerTaskLedgerProjection } from '../task-ledger';
+
+export interface ContextPackIssueFocus { id?: string; title?: string; summary?: string; tasks: ContextPackTaskFocus[] }
+export interface ContextPackTaskFocus { id?: string; title?: string; objective?: string; status?: string }
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
+}
+function string(value: unknown): string | undefined {
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+function task(value: unknown): ContextPackTaskFocus {
+  const item = record(value);
+  return { id: string(item.id), title: string(item.title), objective: string(item.objective), status: string(item.status) };
+}
+function issue(value: unknown): ContextPackIssueFocus {
+  const item = record(value);
+  return {
+    id: string(item.id), title: string(item.title), summary: string(item.summary),
+    tasks: Array.isArray(item.tasks) ? item.tasks.map(task).filter((entry) => Object.keys(entry).length > 0) : [],
+  };
+}
+
+export function issueTaskFocus(
+  board: ReturnType<typeof projectBoard>,
+  issueId?: string,
+  taskId?: string,
+): { issue?: ContextPackIssueFocus; task?: ContextPackTaskFocus } {
+  const issues = board.issues.map(issue);
+  const resolvedIssue = issueId
+    ? issues.find((entry) => entry.id === issueId)
+    : board.currentIssueId ? issues.find((entry) => entry.id === board.currentIssueId) : undefined;
+  return { issue: resolvedIssue, task: resolvedIssue?.tasks.find((entry) => entry.id === taskId) ?? resolvedIssue?.tasks[0] };
+}
+
+export function ledgerTask(
+  ledger: ReturnType<typeof buildControllerTaskLedgerProjection>,
+  issueId?: string,
+  taskId?: string,
+): TaskLedgerTaskProjection | undefined {
+  const tasks = ledger.issues.flatMap((entry) => entry.tasks);
+  const find = (candidateIssueId?: string, candidateTaskId?: string) => tasks
+    .find((entry) => (!candidateIssueId || entry.issueId === candidateIssueId) && (!candidateTaskId || entry.taskId === candidateTaskId));
+  if (!issueId && !taskId) {
+    const ready = ledger.readyTasks[0];
+    return ledger.attention[0] ?? find(ready?.issueId, ready?.taskId) ?? tasks.find((entry) => entry.dispatchable || entry.queueable);
+  }
+  return find(issueId, taskId);
+}

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

@@ -0,0 +1,114 @@
+import { readFileSync } from 'fs';
+import { posix, resolve } from 'path';
+import type { McpPolicy } from '../../mcp/types';
+import { readableFile } from './known-paths';
+
+const CONTRACT_NAMES = ['AGENTS.md', 'CLAUDE.md'] as const;
+const DEFAULT_MAX_TARGETS = 12;
+const DEFAULT_MAX_CONTRACTS = 12;
+const DEFAULT_MAX_CHARS_PER_CONTRACT = 12_000;
+const DEFAULT_MAX_TOTAL_CHARS = 48_000;
+
+export interface RepositoryInstructionContract {
+  path: string;
+  appliesTo: string[];
+  content: string;
+  truncated: boolean;
+}
+
+export interface RepositoryInstructionContext {
+  status: 'none' | 'ready' | 'degraded';
+  authority: 'guidance_only';
+  targetPaths: string[];
+  contracts: RepositoryInstructionContract[];
+  coverageGaps: string[];
+  truncated: boolean;
+}
+
+function isInstructionContract(path: string): boolean {
+  const name = posix.basename(path);
+  return name === 'AGENTS.md' || name === 'CLAUDE.md';
+}
+
+function directoryChain(path: string): string[] {
+  const directory = posix.dirname(path);
+  if (directory === '.' || directory === '/') return [''];
+  const segments = directory.split('/').filter(Boolean);
+  const chain = [''];
+  for (let index = 1; index <= segments.length; index += 1) chain.push(segments.slice(0, index).join('/'));
+  return chain;
+}
+
+export function buildRepositoryInstructionContext(
+  repoRoot: string,
+  policy: McpPolicy,
+  targetPaths: string[],
+  options: { maxTargets?: number; maxContracts?: number; maxCharsPerContract?: number; maxTotalChars?: number } = {},
+): RepositoryInstructionContext {
+  const maxTargets = Math.max(1, Math.min(30, Math.trunc(options.maxTargets ?? DEFAULT_MAX_TARGETS)));
+  const maxContracts = Math.max(1, Math.min(30, Math.trunc(options.maxContracts ?? DEFAULT_MAX_CONTRACTS)));
+  const maxCharsPerContract = Math.max(500, Math.min(50_000, Math.trunc(options.maxCharsPerContract ?? DEFAULT_MAX_CHARS_PER_CONTRACT)));
+  const maxTotalChars = Math.max(2_000, Math.min(100_000, Math.trunc(options.maxTotalChars ?? DEFAULT_MAX_TOTAL_CHARS)));
+  const allTargets = [...new Set(targetPaths.map((path) => path.trim()).filter(Boolean).filter((path) => !isInstructionContract(path)))];
+  const targets = allTargets.slice(0, maxTargets);
+  const coverageGaps: string[] = [];
+  if (allTargets.length > targets.length) coverageGaps.push(`instruction_targets_truncated:${allTargets.length - targets.length}`);
+
+  const contractTargets = new Map<string, Set<string>>();
+  const denied = new Set<string>();
+  for (const target of targets) {
+    for (const directory of directoryChain(target)) {
+      for (const name of CONTRACT_NAMES) {
+        const candidate = directory ? `${directory}/${name}` : name;
+        const readable = readableFile(repoRoot, policy, candidate);
+        if (!readable.ok) {
+          if (!readable.reason.startsWith('path does not exist')) denied.add(`${candidate}:${readable.reason}`);
+          continue;
+        }
+        const appliesTo = contractTargets.get(readable.path) ?? new Set<string>();
+        appliesTo.add(target);
+        contractTargets.set(readable.path, appliesTo);
+      }
+    }
+  }
+  if (denied.size > 0) coverageGaps.push(...[...denied].sort().map((entry) => `instruction_contract_unreadable:${entry}`));
+
+  const orderedPaths = [...contractTargets.keys()].sort((left, right) => {
+    const leftDepth = left.split('/').length;
+    const rightDepth = right.split('/').length;
+    if (leftDepth !== rightDepth) return leftDepth - rightDepth;
+    const leftName = posix.basename(left);
+    const rightName = posix.basename(right);
+    if (leftName !== rightName) return CONTRACT_NAMES.indexOf(leftName as typeof CONTRACT_NAMES[number]) - CONTRACT_NAMES.indexOf(rightName as typeof CONTRACT_NAMES[number]);
+    return left.localeCompare(right);
+  });
+  const selectedPaths = orderedPaths.slice(0, maxContracts);
+  if (orderedPaths.length > selectedPaths.length) coverageGaps.push(`instruction_contracts_truncated:${orderedPaths.length - selectedPaths.length}`);
+
+  const contracts: RepositoryInstructionContract[] = [];
+  const fairContractBudget = Math.max(500, Math.min(maxCharsPerContract, Math.floor(maxTotalChars / Math.max(1, selectedPaths.length))));
+  for (const path of selectedPaths) {
+    try {
+      const raw = readFileSync(resolve(repoRoot, path), 'utf8');
+      const truncated = raw.length > fairContractBudget;
+      contracts.push({
+        path,
+        appliesTo: [...(contractTargets.get(path) ?? new Set<string>())].sort(),
+        content: truncated ? raw.slice(0, fairContractBudget) : raw,
+        truncated,
+      });
+      if (truncated) coverageGaps.push(`instruction_contract_content_truncated:${path}`);
+    } catch (error) {
+      coverageGaps.push(`instruction_contract_read_failed:${path}:${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  return {
+    status: coverageGaps.length > 0 ? 'degraded' : contracts.length > 0 ? 'ready' : 'none',
+    authority: 'guidance_only',
+    targetPaths: targets,
+    contracts,
+    coverageGaps: coverageGaps.slice(0, 30),
+    truncated: allTargets.length > targets.length || orderedPaths.length > selectedPaths.length || contracts.some((entry) => entry.truncated),
+  };
+}

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

@@ -0,0 +1,76 @@
+import { existsSync, lstatSync, readdirSync, statSync } from 'fs';
+import { globMatches, resolveMcpPath } from '../../mcp/paths';
+import type { McpPolicy } from '../../mcp/types';
+
+export function looksLikeGlob(path: string): boolean { return /[*?{[]/.test(path); }
+export function coveredByGlob(path: string, globs: string[]): boolean {
+  return globs.length === 0 || globs.some((glob) => globMatches(glob, path));
+}
+export function addReason(
+  map: Map<string, { reasons: Set<string>; lines: Set<number> }>,
+  path: string,
+  reason: string,
+  line?: number,
+): void {
+  const entry = map.get(path) ?? { reasons: new Set<string>(), lines: new Set<number>() };
+  entry.reasons.add(reason);
+  if (typeof line === 'number' && Number.isFinite(line)) entry.lines.add(Math.max(1, Math.trunc(line)));
+  map.set(path, entry);
+}
+
+export function readableFile(repoRoot: string, policy: McpPolicy, path: string): { ok: true; path: string } | { ok: false; path: string; reason: string } {
+  const decision = resolveMcpPath(repoRoot, path, policy, 'read');
+  if (!decision.ok || !decision.relativePath || !decision.absolutePath) {
+    return { ok: false, path: decision.relativePath ?? path, reason: decision.reason ?? 'path denied' };
+  }
+  if (!existsSync(decision.absolutePath)) return { ok: false, path: decision.relativePath, reason: 'path does not exist' };
+  if (!statSync(decision.absolutePath).isFile()) return { ok: false, path: decision.relativePath, reason: 'path is not a file' };
+  return { ok: true, path: decision.relativePath };
+}
+
+export interface ExpandedKnownPath {
+  files: string[];
+  denied: Array<{ path: string; reason: string }>;
+  directory?: string;
+  truncated: boolean;
+}
+
+export function expandKnownPath(repoRoot: string, policy: McpPolicy, path: string, maxFiles: number): ExpandedKnownPath {
+  const decision = resolveMcpPath(repoRoot, path, policy, 'read');
+  if (!decision.ok || !decision.relativePath || !decision.absolutePath) {
+    return { files: [], denied: [{ path: decision.relativePath ?? path, reason: decision.reason ?? 'path denied' }], truncated: false };
+  }
+  if (!existsSync(decision.absolutePath)) return { files: [], denied: [{ path: decision.relativePath, reason: 'path does not exist' }], truncated: false };
+  const rootStat = lstatSync(decision.absolutePath);
+  if (rootStat.isSymbolicLink()) return { files: [], denied: [{ path: decision.relativePath, reason: 'symbolic links are not followed' }], truncated: false };
+  if (rootStat.isFile()) return { files: [decision.relativePath], denied: [], truncated: false };
+  if (!rootStat.isDirectory()) return { files: [], denied: [{ path: decision.relativePath, reason: 'path is neither a regular file nor directory' }], truncated: false };
+
+  const files: string[] = [];
+  const denied: Array<{ path: string; reason: string }> = [];
+  let truncated = false;
+  const walk = (relativeDirectory: string, depth: number): void => {
+    if (files.length >= maxFiles) { truncated = true; return; }
+    if (depth > 8) { denied.push({ path: relativeDirectory, reason: 'directory recursion depth exceeded' }); return; }
+    const directory = resolveMcpPath(repoRoot, relativeDirectory, policy, 'read');
+    if (!directory.ok || !directory.absolutePath || !directory.relativePath) {
+      denied.push({ path: directory.relativePath ?? relativeDirectory, reason: directory.reason ?? 'path denied' });
+      return;
+    }
+    let entries;
+    try { entries = readdirSync(directory.absolutePath, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name)); }
+    catch (error) { denied.push({ path: directory.relativePath, reason: error instanceof Error ? error.message : String(error) }); return; }
+    for (const entry of entries) {
+      if (files.length >= maxFiles) { truncated = true; break; }
+      const child = `${directory.relativePath}/${entry.name}`.replace(/^\.\//, '');
+      if (entry.isSymbolicLink()) denied.push({ path: child, reason: 'symbolic links are not followed' });
+      else if (entry.isDirectory()) walk(child, depth + 1);
+      else if (entry.isFile()) {
+        const readable = readableFile(repoRoot, policy, child);
+        if (readable.ok) files.push(readable.path); else denied.push(readable);
+      }
+    }
+  };
+  walk(decision.relativePath, 0);
+  return { files, denied, directory: decision.relativePath, truncated };
+}