@moretea-labs/forge 1.6.0 → 1.7.1

package/src/cli/commands/runtime.ts

@@ -13,8 +13,14 @@ import { observeRuntimeStatus } from '../../runtime/root/status';
 import { readMcpServiceBearerToken } from '../mcp/auth';
 import { publishRuntimeRelease } from '../../runtime/root/release-store';
 import { installForgeRuntimeService } from '../../runtime/root/service';
-import { installPackageRuntimeService } from '../../runtime/root/package-runtime-service';
+import { activateScheduledPackageRuntimeServiceFromPath, installPackageRuntimeService, readPackageRuntimeActivationReceipt } from '../../runtime/root/package-runtime-service';
 import { assertRuntimeReleaseFiles, stageRuntimeReleaseFromCandidateSource } from '../../runtime/root/release-materialize';
+import {
+  applyControllerHomeMigration,
+  previewControllerHomeMigration,
+  rollbackControllerHomeMigration,
+  archiveUnroutableMigratedWork,
+} from '../../runtime/control-plane/persistence/controller-home-migration';
 
 function output(value: unknown, json = true): void {
   console.log(json ? JSON.stringify(value, null, 2) : String(value));
@@ -30,6 +36,22 @@ export function buildRuntimeCommand(): Command {
   const service = command.command('service')
     .description('Install or inspect the user-level Forge Runtime owner');
 
+  service.command('activate-package', { hidden: true })
+    .description('Internal one-shot activation helper for a staged package Runtime release')
+    .requiredOption('--request <path>', 'Activation request path')
+    .action(async (opts: { request: string }) => {
+      output(await activateScheduledPackageRuntimeServiceFromPath(opts.request));
+    });
+
+  service.command('activation-status')
+    .description('Read a durable package Runtime activation receipt')
+    .requiredOption('--receipt <path>', 'Activation receipt path returned by install-package')
+    .action((opts: { receipt: string }) => {
+      const receipt = readPackageRuntimeActivationReceipt(resolve(opts.receipt));
+      if (!receipt) throw new Error('RUNTIME_PACKAGE_ACTIVATION_RECEIPT_NOT_FOUND');
+      output(receipt);
+    });
+
   service.command('install-package')
     .description('Install the current packaged Forge Runtime without requiring a Git checkout, Bun compilation, CodeGraph, or Standalone Recovery')
     .option('--controller-home <path>', 'Controller Home; defaults to the user-level Forge Controller Home')
@@ -37,7 +59,8 @@ export function buildRuntimeCommand(): Command {
     .option('--port <port>', 'MCP listener port', '8765')
     .option('--auth-token-file <path>', 'Raw bearer token file (created from user-level MCP config when missing)')
     .option('--portable', 'Force a detached session process instead of launchd/systemd user persistence')
-    .action(async (opts: { controllerHome?: string; host: string; port: string; authTokenFile?: string; portable?: boolean }) => {
+    .option('--refresh-connector', 'Explicitly replace/restart the persistent public MCP Gateway instead of reusing a healthy existing Gateway')
+    .action(async (opts: { controllerHome?: string; host: string; port: string; authTokenFile?: string; portable?: boolean; refreshConnector?: boolean }) => {
       const home = resolveControllerHome(opts.controllerHome);
       const port = Number(opts.port);
       if (!Number.isInteger(port) || port < 1 || port > 65_535) throw new Error('RUNTIME_SERVICE_PORT_INVALID');
@@ -56,6 +79,7 @@ export function buildRuntimeCommand(): Command {
         port,
         authTokenFile: tokenPath,
         forcePortable: opts.portable === true,
+        refreshConnector: opts.refreshConnector === true,
       });
       output({
         status: result.status,
@@ -73,8 +97,11 @@ export function buildRuntimeCommand(): Command {
         servicePath: result.servicePath,
         pid: result.pid,
         connector: result.connector,
+        activation: result.activation,
         warnings: result.warnings,
-        next: `forge runtime status --controller-home ${home}`,
+        next: result.activation
+          ? `forge runtime service activation-status --receipt ${result.activation.receiptPath}`
+          : `forge runtime status --controller-home ${home}`,
       });
     });
 
@@ -163,6 +190,31 @@ export function buildRuntimeCommand(): Command {
       });
     });
 
+  command.command('migrate-controller-home')
+    .description('Preview or transactionally migrate non-terminal business state from an explicitly selected retired Controller Home')
+    .requiredOption('--source <path>', 'Retired Controller Home to inspect; repository presence never selects this implicitly')
+    .option('--destination <path>', 'Canonical Controller Home; defaults to the installed user-level authority')
+    .option('--apply', 'Apply the reviewed migration and freeze the source SQLite as a read-only archive')
+    .option('--rollback <migration-id>', 'Rollback one migration only when none of its imported records changed')
+    .option('--archive-unroutable <migration-id>', 'Archive imported nonterminal Work whose repository is not registered in the canonical Home')
+    .action(async (opts: { source: string; destination?: string; apply?: boolean; rollback?: string; archiveUnroutable?: string }) => {
+      const destination = resolveControllerHome(opts.destination);
+      if (opts.archiveUnroutable?.trim()) {
+        output(archiveUnroutableMigratedWork({ destinationHome: destination, migrationId: opts.archiveUnroutable.trim() }));
+        return;
+      }
+      if (opts.rollback?.trim()) {
+        output(rollbackControllerHomeMigration({ destinationHome: destination, migrationId: opts.rollback.trim() }));
+        return;
+      }
+      const input = { sourceHome: resolve(opts.source), destinationHome: destination };
+      if (opts.apply === true) {
+        output(await applyControllerHomeMigration(input));
+        return;
+      }
+      output(await previewControllerHomeMigration(input));
+    });
+
   command.command('status')
     .description('Read the Runtime Root status projection, active durable Jobs, and materialized repository projections')
     .requiredOption('--controller-home <path>', 'Explicit Controller Home')

package/src/cli/commands/security.ts

@@ -8,7 +8,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { execFileSync } from 'child_process';
-import { MANAGED_TAG, type HookEntry } from '../installer/managed-entries';
+import { MANAGED_TAG, isLegacyRepoHarnessCommand, type HookEntry } from '../installer/managed-entries';
 
 export type SecurityStatus = 'ok' | 'warn' | 'fail';
 export type SecuritySeverity = 'warn' | 'high' | 'fail';
@@ -273,6 +273,17 @@ function scanHookConfig(
     if (!command) continue;
     const suspicious = suspiciousMatch(command);
     if (command.includes(MANAGED_TAG) && suspicious === null) continue;
+    if (isLegacyRepoHarnessCommand(command)) {
+      findings.push({
+        filePath,
+        ruleId: 'legacy-repo-harness-hook-adapter',
+        severity: 'warn',
+        summary: `${hostLabel} ${event} hook uses the retired repo-harness adapter`,
+        recommendation: 'Run forge install --target codex --location global to replace retired adapters with forge-hook.',
+        command,
+      });
+      continue;
+    }
     findings.push({
       filePath,
       ruleId: suspicious?.ruleId ?? 'unmanaged-hook-command',

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;
@@ -675,6 +773,8 @@ export function runControllerCheck(repoRoot: string, id: string, requestedTimeou
 
 export interface AsyncControllerCheckOptions {
   snapshot?: ControllerCheckSnapshot;
+  /** Explicit isolated authority for Candidate verification child processes. */
+  isolatedControllerHome?: string;
   requestedTimeoutMs?: number;
   onSpawn?: (pid: number) => void;
   subscriberId?: string;
@@ -814,12 +914,15 @@ async function executeControllerCheckAsync(
   check: ControllerCheck,
   timeoutMs: number,
   onSpawn?: (pid: number) => void,
+  isolatedControllerHome?: string,
 ): Promise<ControllerCheckResult> {
   const maxOutputBytes = 256 * 1024;
   const command = [check.command[0], ...check.command.slice(1)];
+  const childEnvironment = repositoryChildProcessEnvironment();
+  if (isolatedControllerHome?.trim()) childEnvironment.FORGE_CONTROLLER_HOME = resolve(isolatedControllerHome);
   const supervised = await runBoundedChild(check.command[0], check.command.slice(1), {
     cwd: resolve(repoRoot, check.cwd),
-    env: repositoryChildProcessEnvironment(),
+    env: childEnvironment,
     timeoutMs,
     maxOutputBytes,
     stdio: 'capture',
@@ -877,6 +980,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;
@@ -947,7 +1055,7 @@ export function runControllerCheckAsync(
     const result = await executeControllerCheckAsync(repoRoot, check, timeoutMs, (pid) => {
       lease?.setChildPid(pid);
       notifySpawn(pid);
-    });
+    }, options.isolatedControllerHome);
     const completedRevision = currentControllerCheckRevision(repoRoot);
     const stale = completedRevision !== revision;
     const finalized = {

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),
+  };
+}