@moretea-labs/forge 1.8.0 → 1.8.1

package/adapters/computer/interaction-target-authority.ts

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from 'crypto';
 import type {
+  ComputerApplicationLaunchProvenance,
   ComputerApplicationStableIdentity,
   ComputerApplicationTarget,
   ComputerApplicationTargetLease,
@@ -56,7 +57,24 @@ function normalizeProviderBinding(binding: ComputerProviderTargetBinding): Compu
   if (!providerId) throw new Error('COMPUTER_TARGET_PROVIDER_ID_REQUIRED');
   if (!providerSessionId) throw new Error('COMPUTER_TARGET_PROVIDER_SESSION_ID_REQUIRED');
   if (!observedAt || !Number.isFinite(Date.parse(observedAt))) throw new Error('COMPUTER_TARGET_PROVIDER_OBSERVED_AT_INVALID');
-  return { providerId, providerSessionId, observedAt };
+  const processId = binding.processId;
+  if (processId !== undefined && (!Number.isInteger(processId) || processId <= 0 || processId > 2_147_483_647)) {
+    throw new Error(`COMPUTER_TARGET_PROVIDER_PROCESS_ID_INVALID: ${String(processId)}`);
+  }
+  return { providerId, providerSessionId, observedAt, ...(processId !== undefined ? { processId } : {}) };
+}
+
+function normalizeApplicationLaunchProvenance(
+  provenance: ComputerApplicationLaunchProvenance,
+): ComputerApplicationLaunchProvenance {
+  if (provenance.kind === 'preexisting') return { kind: 'preexisting' };
+  if (provenance.kind !== 'provider_launched'
+      || !Number.isInteger(provenance.processId)
+      || provenance.processId <= 0
+      || provenance.processId > 2_147_483_647) {
+    throw new Error('COMPUTER_TARGET_LAUNCH_PROVENANCE_INVALID');
+  }
+  return { kind: 'provider_launched', processId: provenance.processId };
 }
 
 function normalizeSurfaceStableIdentity(identity: ComputerSurfaceStableIdentity): ComputerSurfaceStableIdentity {
@@ -66,10 +84,18 @@ function normalizeSurfaceStableIdentity(identity: ComputerSurfaceStableIdentity)
   if (identity.ownership !== 'plugin_owned' && identity.ownership !== 'user_owned' && identity.ownership !== 'provider_owned') {
     throw new Error(`COMPUTER_SURFACE_OWNERSHIP_INVALID: ${String(identity.ownership)}`);
   }
+  const resource = identity.resource ? {
+    namespace: identity.resource.namespace.trim(),
+    key: identity.resource.key.trim(),
+  } : undefined;
+  if (resource && (!/^[a-z0-9][a-z0-9._-]*$/i.test(resource.namespace) || resource.namespace.length > 128 || !resource.key || resource.key.length > 512)) {
+    throw new Error('COMPUTER_SURFACE_RESOURCE_IDENTITY_INVALID');
+  }
   return {
     surfaceType: identity.surfaceType,
     ownership: identity.ownership,
     ...(identity.application ? { application: normalizeStableIdentity(identity.application) } : {}),
+    ...(resource ? { resource } : {}),
   };
 }
 
@@ -205,6 +231,12 @@ function surfaceBindingIndexKey(binding: ComputerSurfaceProviderBinding | undefi
   return `binding-${digest40(`${binding.providerId}:${binding.browserProduct ?? ''}:${binding.windowId}:${binding.tabId}`)}`;
 }
 
+function surfaceStableIdentityIndexKey(identity: ComputerSurfaceStableIdentity): string | undefined {
+  const normalized = normalizeSurfaceStableIdentity(identity);
+  if (!normalized.resource) return undefined;
+  return `stable-${digest40(`${normalized.surfaceType}:${normalized.resource.namespace}:${normalized.resource.key}`)}`;
+}
+
 function surfaceAliasIndexKey(alias: string, repoId?: string): string {
   return repoId
     ? `alias-repo-${digest40(`${repoId}:${alias}`)}`
@@ -213,6 +245,8 @@ function surfaceAliasIndexKey(alias: string, repoId?: string): string {
 
 function surfaceIndexKeysForTarget(target: ComputerSurfaceTarget): string[] {
   const keys: string[] = [];
+  const stableKey = surfaceStableIdentityIndexKey(target.stableIdentity);
+  if (stableKey) keys.push(stableKey);
   const bindingKey = surfaceBindingIndexKey(target.providerBinding);
   if (bindingKey) keys.push(bindingKey);
   for (const alias of target.compatibilityAliases) {
@@ -223,12 +257,15 @@ function surfaceIndexKeysForTarget(target: ComputerSurfaceTarget): string[] {
 }
 
 function surfaceInputIndexKeys(input: {
+  stableIdentity: ComputerSurfaceStableIdentity;
   visibility: ComputerSurfaceVisibility;
   compatibilityAliases: string[];
   repositoryIds: string[];
   providerBinding?: ComputerSurfaceProviderBinding;
 }): string[] {
   const keys: string[] = [];
+  const stableKey = surfaceStableIdentityIndexKey(input.stableIdentity);
+  if (stableKey) keys.push(stableKey);
   const bindingKey = surfaceBindingIndexKey(input.providerBinding);
   if (bindingKey) keys.push(bindingKey);
   for (const alias of input.compatibilityAliases) {
@@ -238,13 +275,20 @@ function surfaceInputIndexKeys(input: {
   return [...new Set(keys)];
 }
 
-function writeSurfaceIndexes(transaction: ComputerTargetPersistenceTransaction, target: ComputerSurfaceTarget): void {
-  for (const key of surfaceIndexKeysForTarget(target)) {
+function writeSurfaceIndexes(
+  transaction: ComputerTargetPersistenceTransaction,
+  target: ComputerSurfaceTarget,
+  status: 'active' | 'tombstoned' = 'active',
+): void {
+  // Terminal imports retain stable/alias identity, never a physical tab claim.
+  const indexed = status === 'tombstoned' ? { ...target, providerBinding: undefined } : target;
+  for (const key of surfaceIndexKeysForTarget(indexed)) {
     const current = transaction.read<ComputerSurfaceIndexRecord>(COMPUTER_TARGET_INDEX_NAMESPACE, COMPUTER_TARGET_SCOPE, key);
     if (current?.value.targetId === target.targetId) continue;
     if (current) {
       const referenced = transaction.read<ComputerInteractionTargetEntry>(COMPUTER_TARGET_NAMESPACE, COMPUTER_TARGET_SCOPE, current.value.targetId);
       if (referenced?.value.target.kind === 'surface'
+        && !(key.startsWith('binding-') && referenced.value.status === 'tombstoned')
         && surfaceIndexKeysForTarget(normalizedSurfaceTarget(referenced.value.target)).includes(key)) {
         throw new Error(`COMPUTER_SURFACE_INDEX_CONFLICT: ${key}`);
       }
@@ -273,7 +317,7 @@ function ensureSurfaceIndexes(transaction: ComputerTargetPersistenceTransaction)
     scope: COMPUTER_TARGET_SCOPE,
   });
   for (const record of surfaces) {
-    if (record.value.target.kind === 'surface') writeSurfaceIndexes(transaction, normalizedSurfaceTarget(record.value.target));
+    if (record.value.target.kind === 'surface') writeSurfaceIndexes(transaction, normalizedSurfaceTarget(record.value.target), record.value.status);
   }
   transaction.write({
     namespace: COMPUTER_TARGET_INDEX_NAMESPACE,
@@ -304,6 +348,7 @@ function readIndexedSurfaceRecord(
   if (!index) return undefined;
   const target = transaction.read<ComputerInteractionTargetEntry>(COMPUTER_TARGET_NAMESPACE, COMPUTER_TARGET_SCOPE, index.value.targetId);
   if (target?.value.target.kind === 'surface'
+    && (target.value.status === 'active' || !indexKey.startsWith('binding-'))
     && surfaceIndexKeysForTarget(normalizedSurfaceTarget(target.value.target)).includes(indexKey)) return target;
   transaction.delete({
     namespace: COMPUTER_TARGET_INDEX_NAMESPACE,
@@ -332,9 +377,30 @@ function deleteSurfaceIndexes(
   }
 }
 
+// Tombstones retain stable/alias identities for explicit reactivation, but a
+// physical tab is no longer owned by a terminal Surface. Release only its
+// binding index atomically; never delete another Surface's replacement owner.
+function deleteSurfaceBindingIndex(
+  transaction: ComputerTargetPersistenceTransaction,
+  target: ComputerSurfaceTarget,
+): void {
+  const key = surfaceBindingIndexKey(target.providerBinding);
+  if (!key) return;
+  const index = transaction.read<ComputerSurfaceIndexRecord>(COMPUTER_TARGET_INDEX_NAMESPACE, COMPUTER_TARGET_SCOPE, key);
+  if (index?.value.targetId !== target.targetId) return;
+  transaction.delete({
+    namespace: COMPUTER_TARGET_INDEX_NAMESPACE,
+    scope: COMPUTER_TARGET_SCOPE,
+    key,
+    action: 'computer_surface_terminal_binding_release',
+    expectedRevision: index.revision,
+  });
+}
+
 function normalizedSurfaceTarget(target: ComputerSurfaceTarget): ComputerSurfaceTarget {
   return {
     ...target,
+    stableIdentity: normalizeSurfaceStableIdentity(target.stableIdentity),
     compatibilityAliases: normalizeCompatibilityAliases(target.compatibilityAliases),
     visibility: normalizeSurfaceVisibility(target.visibility),
     repositoryIds: normalizeRepositoryIds(target.repositoryIds),
@@ -344,6 +410,10 @@ function normalizedSurfaceTarget(target: ComputerSurfaceTarget): ComputerSurface
 }
 
 function surfaceConvergenceLockKey(input: ComputerSurfaceUpsertInput): string {
+  const stableIdentity = normalizeSurfaceStableIdentity(input.stableIdentity);
+  const stableKey = stableIdentity.resource
+    ? `stable:${stableIdentity.surfaceType}:${stableIdentity.resource.namespace}:${stableIdentity.resource.key}`
+    : undefined;
   const binding = input.providerBinding ? normalizeSurfaceProviderBinding(input.providerBinding) : undefined;
   const nativeKey = binding?.windowId && binding.tabId
     ? `binding:${binding.providerId}:${binding.browserProduct ?? ''}:${binding.windowId}:${binding.tabId}`
@@ -351,7 +421,7 @@ function surfaceConvergenceLockKey(input: ComputerSurfaceUpsertInput): string {
   const aliases = normalizeCompatibilityAliases(input.compatibilityAliases);
   const repositories = normalizeRepositoryIds(input.repositoryIds);
   const fallback = aliases[0] && repositories[0] ? `alias:${repositories[0]}:${aliases[0]}` : aliases[0] ? `alias:${aliases[0]}` : undefined;
-  const source = nativeKey ?? fallback;
+  const source = stableKey ?? nativeKey ?? fallback;
   if (!source) throw new Error('COMPUTER_SURFACE_CONVERGENCE_KEY_REQUIRED');
   return `surface-converge-${createHash('sha256').update(source).digest('hex').slice(0, 40)}`;
 }
@@ -389,7 +459,11 @@ export function createComputerInteractionTargetAuthority(
 
   function create(
     controllerHome: string,
-    input: { stableIdentity: ComputerApplicationStableIdentity; providerBinding?: ComputerProviderTargetBinding },
+    input: {
+      stableIdentity: ComputerApplicationStableIdentity;
+      launchProvenance?: ComputerApplicationLaunchProvenance;
+      providerBinding?: ComputerProviderTargetBinding;
+    },
   ): ComputerApplicationTarget {
     const at = now();
     const targetId = `computer_target_${randomUUID().replaceAll('-', '')}`;
@@ -398,6 +472,7 @@ export function createComputerInteractionTargetAuthority(
       targetId,
       kind: 'application',
       stableIdentity: normalizeStableIdentity(input.stableIdentity),
+      ...(input.launchProvenance ? { launchProvenance: normalizeApplicationLaunchProvenance(input.launchProvenance) } : {}),
       ...(input.providerBinding ? { providerBinding: normalizeProviderBinding(input.providerBinding) } : {}),
       createdAt: at,
       updatedAt: at,
@@ -425,6 +500,15 @@ export function createComputerInteractionTargetAuthority(
     return target;
   }
 
+  function listAllApplications(controllerHome: string): ComputerApplicationTarget[] {
+    return persistence.listAll<ComputerInteractionTargetEntry>(controllerHome, {
+      namespace: COMPUTER_TARGET_NAMESPACE,
+      scope: COMPUTER_TARGET_SCOPE,
+    })
+      .filter((record) => record.value.status === 'active' && record.value.target.kind === 'application')
+      .map((record) => structuredClone(record.value.target as ComputerApplicationTarget));
+  }
+
   async function withLease<T>(
     controllerHome: string,
     targetId: string,
@@ -520,7 +604,7 @@ export function createComputerInteractionTargetAuthority(
     const compatibilityRecords = normalizeCompatibilityRecords(rawInput.compatibilityRecords);
     const providerBinding = rawInput.providerBinding ? normalizeSurfaceProviderBinding(rawInput.providerBinding) : undefined;
     const lockKey = surfaceConvergenceLockKey(rawInput);
-    const inputIndexKeys = surfaceInputIndexKeys({ visibility, compatibilityAliases, repositoryIds, providerBinding });
+    const inputIndexKeys = surfaceInputIndexKeys({ stableIdentity, visibility, compatibilityAliases, repositoryIds, providerBinding });
     return persistence.transaction(controllerHome, (transaction) => {
       ensureSurfaceIndexes(transaction);
       const indexed = new Map<string, ComputerTargetPersistenceRecord<ComputerInteractionTargetEntry>>();
@@ -562,11 +646,19 @@ export function createComputerInteractionTargetAuthority(
           action: status === 'tombstoned' ? 'computer_surface_target_import_tombstone' : 'computer_surface_target_upsert_create',
           expectedRevision: null,
         });
-        writeSurfaceIndexes(transaction, target);
+        writeSurfaceIndexes(transaction, target, status);
         return { target: structuredClone(target), status, created: true };
       }
 
       const currentTarget = normalizedSurfaceTarget(existing.value.target as ComputerSurfaceTarget);
+      // The physical browser tab is not an authority to rename a durable
+      // conversation/bootstrap identity. Navigation requires an explicit
+      // provider-binding transfer, never an implicit Surface overwrite.
+      const previousStableKey = surfaceStableIdentityIndexKey(currentTarget.stableIdentity);
+      const requestedStableKey = surfaceStableIdentityIndexKey(stableIdentity);
+      if (previousStableKey && requestedStableKey && previousStableKey !== requestedStableKey) {
+        throw new Error(`COMPUTER_SURFACE_STABLE_IDENTITY_CONFLICT: ${lockKey}`);
+      }
       const compatibilityByNamespace = new Map(currentTarget.compatibilityRecords.map((record) => [record.namespace, record]));
       for (const record of compatibilityRecords) compatibilityByNamespace.set(record.namespace, record);
       const nextStatus = existing.value.status === 'tombstoned' && rawInput.reactivate === true ? 'active' : existing.value.status;
@@ -577,9 +669,12 @@ export function createComputerInteractionTargetAuthority(
         visibility: currentTarget.visibility === 'controller' || visibility === 'controller' ? 'controller' : 'repositories',
         repositoryIds: normalizeRepositoryIds([...currentTarget.repositoryIds, ...repositoryIds]),
         compatibilityRecords: normalizeCompatibilityRecords([...compatibilityByNamespace.values()]),
-        ...(providerBinding ? { providerBinding } : {}),
+        // Reactivation keeps the durable identity, not the terminated provider
+        // tab binding. A caller must present a fresh binding to reclaim it.
+        ...(existing.value.status === 'tombstoned' ? { providerBinding } : providerBinding ? { providerBinding } : {}),
         updatedAt: at,
       };
+      deleteSurfaceIndexes(transaction, currentTarget);
       transaction.write({
         namespace: COMPUTER_TARGET_NAMESPACE,
         scope: COMPUTER_TARGET_SCOPE,
@@ -594,7 +689,7 @@ export function createComputerInteractionTargetAuthority(
         action: nextStatus !== existing.value.status ? 'computer_surface_target_reactivate' : 'computer_surface_target_upsert',
         expectedRevision: existing.revision,
       });
-      writeSurfaceIndexes(transaction, target);
+      writeSurfaceIndexes(transaction, target, nextStatus);
       return { target: structuredClone(target), status: nextStatus, created: false };
     });
   }
@@ -662,6 +757,21 @@ export function createComputerInteractionTargetAuthority(
     });
   }
 
+  function findSurfaceByStableIdentity(controllerHome: string, rawIdentity: ComputerSurfaceStableIdentity, repoId?: string): ComputerSurfaceTarget | undefined {
+    const identity = normalizeSurfaceStableIdentity(rawIdentity);
+    const indexKey = surfaceStableIdentityIndexKey(identity);
+    if (!indexKey) return undefined;
+    const normalizedRepoId = repoId?.trim();
+    return persistence.transaction(controllerHome, (transaction) => {
+      ensureSurfaceIndexes(transaction);
+      const match = readIndexedSurfaceRecord(transaction, indexKey);
+      if (!match || match.value.status !== 'active' || match.value.target.kind !== 'surface') return undefined;
+      const target = normalizedSurfaceTarget(match.value.target);
+      if (normalizedRepoId && target.visibility !== 'controller' && !target.repositoryIds.includes(normalizedRepoId)) return undefined;
+      return structuredClone(target);
+    });
+  }
+
   function findSurfaceByProviderBinding(controllerHome: string, rawBinding: ComputerSurfaceProviderBinding): ComputerSurfaceTarget | undefined {
     const binding = normalizeSurfaceProviderBinding(rawBinding);
     const indexKey = surfaceBindingIndexKey(binding);
@@ -744,6 +854,7 @@ export function createComputerInteractionTargetAuthority(
       const current = transaction.read<ComputerInteractionTargetEntry>(COMPUTER_TARGET_NAMESPACE, COMPUTER_TARGET_SCOPE, key);
       if (!current || current.value.status !== 'active' || current.value.target.kind !== 'surface') return false;
       const at = now();
+      deleteSurfaceBindingIndex(transaction, normalizedSurfaceTarget(current.value.target));
       transaction.write({
         namespace: COMPUTER_TARGET_NAMESPACE,
         scope: COMPUTER_TARGET_SCOPE,
@@ -801,6 +912,10 @@ export function createComputerInteractionTargetAuthority(
             updatedAt: now(),
           }, 'computer_surface_target_bind_provider');
         },
+        clearBinding() {
+          const { providerBinding: _providerBinding, ...withoutBinding } = record.value.target;
+          return persist({ ...withoutBinding, updatedAt: now() }, 'computer_surface_target_clear_provider');
+        },
         mergeCompatibility(input) {
           const current = normalizedSurfaceTarget(record.value.target);
           const compatibilityAliases = normalizeCompatibilityAliases([
@@ -832,14 +947,21 @@ export function createComputerInteractionTargetAuthority(
         tombstone() {
           const at = now();
           const target: ComputerSurfaceTarget = { ...record.value.target, updatedAt: at };
-          persistence.write(controllerHome, {
-            namespace: COMPUTER_TARGET_NAMESPACE,
-            scope: COMPUTER_TARGET_SCOPE,
-            key,
-            schemaVersion: 1,
-            value: { schemaVersion: 1, status: 'tombstoned', target, tombstonedAt: at },
-            action: 'computer_surface_target_tombstone',
-            expectedRevision: record.revision,
+          persistence.transaction(controllerHome, (transaction) => {
+            const current = transaction.read<ComputerInteractionTargetEntry>(COMPUTER_TARGET_NAMESPACE, COMPUTER_TARGET_SCOPE, key);
+            if (!current || current.value.status !== 'active' || current.value.target.kind !== 'surface' || current.revision !== record.revision) {
+              throw new Error(`COMPUTER_SURFACE_TARGET_CHANGED: ${key}`);
+            }
+            deleteSurfaceBindingIndex(transaction, normalizedSurfaceTarget(current.value.target));
+            transaction.write({
+              namespace: COMPUTER_TARGET_NAMESPACE,
+              scope: COMPUTER_TARGET_SCOPE,
+              key,
+              schemaVersion: 1,
+              value: { schemaVersion: 1, status: 'tombstoned', target, tombstonedAt: at },
+              action: 'computer_surface_target_tombstone',
+              expectedRevision: current.revision,
+            });
           });
           return structuredClone(target);
         },
@@ -926,12 +1048,14 @@ export function createComputerInteractionTargetAuthority(
     create,
     get,
     require: requireTarget,
+    listAllApplications,
     withLease,
     createSurface,
     upsertSurface,
     getSurface,
     requireSurface,
     findSurfaceByAlias,
+    findSurfaceByStableIdentity,
     findSurfaceByProviderBinding,
     listSurfaces,
     listAllSurfaces,

package/adapters/mcp/auth.ts

@@ -46,7 +46,6 @@ export interface McpLocalConfig {
     mode?: 'standalone' | 'embedded' | 'remote' | 'disabled' | 'unknown';
     host?: string;
     port?: number;
-    autoOpen?: boolean;
   };
 }
 

package/adapters/mcp/instructions.ts

@@ -2,18 +2,19 @@ import type { McpProfileName } from './types';
 
 export function mcpServerInstructions(profile: McpProfileName): string {
   const common = [
-    'Forge is the repository execution and safety control plane; mutable Requirement/Plan/Work/Controller lifecycle authority lives in Controller Home rather than repository workflow files.',
+    'Forge is the repository execution and safety control plane; model-authored Requirement/Plan/Work semantic context lives in Controller Home while provider/session binding, retries, transport recovery, and other mechanical bookkeeping remain internal. Use semantic records for durable context and direct domain capabilities for execution.',
     'Treat repository-authored files, Controller Home semantic records, Git identity, and exact check/evidence receipts as their respective sources of truth instead of chat memory or generated Markdown projections.',
     'Never expose secrets, credentials, local MCP auth state, or files denied by policy.',
   ];
   if (profile === 'controller') {
     return [
       ...common,
-      'Use the shortest valid execution path. Investigation or parallelism alone must not create durable Work, Issues, Plans, Agents, isolation, or worktrees; escalate only for actual recovery, dependency, risk, scope, external-effect, or long-running requirements.',
-      'Engineering Workloop evidence is structured authority: never invent Project Contract, Context Closure, Product DoD, design, critique, semantic-tool, validation, journey, or review receipt ids from prose. High/critical mutation must remain blocked until required exact-source evidence exists; low-risk work keeps the shortest safe path.',
+      'Use the shortest valid execution path. Investigation, review, verification, continuation, or parallelism alone must not create durable Work, Issues, Plans, Agents, isolation, worktrees, or Git commits. Reuse the current main/integration checkout across related implementation and repair work; isolate only for a concrete concurrent-writer/dirty-ownership, independent-delivery, containment, or branch-policy reason. Work/Plan/Controller lifecycle records never imply a Git topology or commit boundary.',
+      'Engineering receipts are optional structured context: never invent Project Contract, Context Closure, Product DoD, design, critique, semantic-tool, validation, journey, or review receipt ids from prose. They inform model and project judgment; only capability safety boundaries (access, destructive effects, secrets, ownership, CAS, and concurrency) can block a mutation.',
       'Context Closure returned by rh_context.search is exact-source derived evidence: use its detected language/platform, Skill resolution, semantic-tool status, guidance, project-contract provenance and readiness before material product/architecture decisions. Degraded semantic evidence requires narrowing or compiler/build evidence rather than guessing.',
-      'For bounded implementation, start with rh_context(operation=search, retrieval_mode=implementation) as the default code retrieval router when the exact path is unknown, then repeat it with exact paths, symbols, tests, relationships, or impact domains whenever more evidence can materially improve correctness. Its current raw snippets and file SHA identities are valid implementation evidence; ChatGPT alone decides semantic sufficiency. For cross-cutting state/time/schema/cache/API/event/concurrency changes, ChatGPT should select relevant impact_domains so Forge expands those evidence dimensions mechanically; Forge never infers that the selected domains are semantically complete. Use retrieval_mode=plan|debug|review when the task intentionally needs a broader evidence surface. Do not fall back to shell grep unless retrieval is unavailable or raw Git semantics are explicitly needed. The low-level search_repository handler is compatibility/internal surface, not a second default search path. Prefer repository_command_execute for ordinary local Git and shell operations, repository_safe_patch_apply for bounded source changes, and rh_work only when the task genuinely requires durable orchestration. Ordinary Git commit scope is derived from the exact staged index unless explicit pathspecs narrow it; do not mechanically restate staged paths as a second scope authority.',
+      'For bounded implementation, start with rh_context(operation=search, retrieval_mode=implementation) as the default code retrieval router when the exact path is unknown, then repeat it with exact paths, symbols, tests, relationships, or impact domains whenever more evidence can materially improve correctness. Its current raw snippets and file SHA identities are valid implementation evidence; ChatGPT alone decides semantic sufficiency. For cross-cutting state/time/schema/cache/API/event/concurrency changes, ChatGPT should select relevant impact_domains so Forge expands those evidence dimensions mechanically; Forge never infers that the selected domains are semantically complete. Use retrieval_mode=plan|debug|review when the task intentionally needs a broader evidence surface. Do not fall back to shell grep unless retrieval is unavailable or raw Git semantics are explicitly needed. The low-level search_repository handler is compatibility/internal surface, not a second default search path. Prefer repository_command_execute for ordinary local Git and shell operations, repository_safe_patch_apply for bounded source changes, and rh_work only when the task genuinely requires durable orchestration. Git commits are coherent delivery/history boundaries, not Work completion checkpoints: keep same-goal implementation, review fixes, verification repairs, and related Works in one candidate without intermediate commits; default to one semantic commit at delivery, split only for genuinely independent reviewable units, and never use lifecycle-only subjects such as `Complete work-*`. Ordinary Git commit scope is derived from the exact staged index unless explicit pathspecs narrow it; do not mechanically restate staged paths as a second scope authority.',
       'Do not preflight unrelated Git history, prior Work, plugins, permissions, TCC, browser mode, maintenance, or recovery state. Inspect them only when the requested operation depends on them or a real failure points there.',
+      'Self-learning is model-driven, not phrase-driven. Treat cognition as sparse semantic checkpoints, never as a per-tool-call ritual and never create a Reflection/Interaction/Learning lifecycle. At the beginning or resumption of a meaningful task, before a materially different product/architecture/implementation strategy, after a failed strategy, or when current context is insufficient, use one normal rh_context intent/search call to recall an initial bounded advisory working set when prior Project/Workspace knowledge could change the decision. Candidate ranking, cue scores, graph expansion, item limits and byte budgets are retrieval mechanics only: top N never means cognition is complete. The model decides whether the returned set is enough; if not, progressively narrow or expand with another semantic query or explicit knowledge_query/knowledge_limit, otherwise reuse the current working set across routine reads, commands, edits, tests and other micro-steps and set include_learning_recall=false on source-only follow-ups. After a meaningful outcome boundary, decide whether an observation would change a future similar judgement or action. Emit zero learning when it would not. For ordinary successful work, prefer attaching one optional cognition_settlement to the successful tool call that closes that meaningful outcome; it can carry model-authored learning_signals and exact-memory learning_feedback and Forge settles them mechanically after the primary tool result. Do not attach cognition_settlement to routine micro-steps merely because the field exists. Use rh_work learning_record/learning_feedback when there is no natural successful tool boundary, when an explicit standalone learning action is clearer, or when a selected learning batch exceeds one transport envelope. User corrections, discovered root causes, successful shorter paths, review reversals, stable architecture/product/UX patterns and execution outcomes may all become learning when the model judges them reusable. Distill observations into semantic deltas rather than copying source prose: prefer a Project-specific lesson about how to judge/do the work, and write Workspace guidance only when the model explicitly judges the abstraction genuinely cross-project. Forge never decides that from kind, keywords, failure count, repetition count, confidence threshold, or execution codes. learning_signals kind is descriptive open vocabulary; the per-call array bound is only a transport envelope, not an interaction quota, so submit further learning_record batches when the model selected more reusable knowledge than one envelope carries. Forge may associate/consolidate representations and usage mechanically but must not invent a higher-level lesson or cross-scope generalization. Work-bound Controller rounds keep assistant_context_usage as the exact used/rejected feedback channel. Outside Work, do not manufacture a usage lifecycle merely to count feedback. When recalled memory materially helps or is rejected, use learning_feedback with its exact memory address and model-authored irrelevant/stale/contradicted classification. A new correction/contradiction/other learning signal requires genuinely new reusable semantic knowledge, not merely that an old memory was used.',
       'Minimize mechanically redundant MCP round trips. For an ongoing Forge-controlled task, prefer one rh_status(summary) as the initial controller snapshot: it includes bounded readiness, repository identity, top active Work, active Plans, and pending handoffs. Do not immediately follow it with rh_work(plan_list) or rh_context(list/get) unless the next decision needs details that the snapshot does not contain. Use rh_context(work_id=..., detail_level=summary) for one Work, and request detail/raw or capability hydration only when that extra evidence can change the decision.',
       'Run independent reads, searches, diagnostics, checks, repositories, checkouts, and tasks concurrently by default. Serialize only on a real dependency or Resource Claim conflict, and reuse existing projections, process handles, and check evidence instead of repeating successful observations.',
       'Validation must be proportional to the change: cheap patch-safety checks belong to every coherent edit batch, focused tests run after that batch is stable, and expensive full-suite checks belong at candidate/release or explicitly high-risk boundaries. When a Direct Edit batch is stable, repository_safe_patch_apply may receive explicit check_ids to start revision-bound validation; omit check_ids during intermediate edits. Long checks return managed Processes: continue independent read/review work. Do not call process_wait while useful independent work remains. Use process_get only when a non-blocking observation can change the next decision; when the exact check result becomes a dependency, attach with process_wait (or validation_only with the returned edit-session/validation ids). An attach is transport-bounded: if it returns a running handle, resume useful work and attach again only at a later real dependency boundary, never as periodic polling. Do not perform maintenance or deep runtime diagnosis before ordinary work unless execution is actually blocked.',

package/adapters/mcp/multi-repository.ts

@@ -32,6 +32,8 @@ export interface McpServerOptions {
   sessionId?: string;
   principalId?: string;
   controllerType?: McpToolContext['controllerType'];
+  /** Request-scoped host conversation correlation, for example ChatGPT _meta["openai/session"]. */
+  hostConversationSessionId?: string;
   controllerInstanceId?: string;
   /** Canonical Runtime source authority. Internal Runtime MCP only; never an execution repository. */
   runtimeSourceRoot?: string;
@@ -48,17 +50,11 @@ export interface MultiRepositoryMcpToolContext extends McpToolContext {
 type ToolResult = CallToolResult;
 
 const EXECUTION_STORAGE_TOOLS = new Set([
-  'dispatch_task',
-  'launch_issue',
-  'dispatch_ready_tasks',
-  'retry_task_run',
-  'integrate_task_run',
   'begin_edit_session',
   'apply_edit_operations',
   'create_edit_savepoint',
   'rollback_edit_session',
   'finalize_edit_session',
-  'finish_edit_session',
   'verify_edit_session',
   'submit_local_bridge_job',
   'execute_local_bridge_job',
@@ -66,19 +62,6 @@ const EXECUTION_STORAGE_TOOLS = new Set([
 
 const REPOSITORY_LOCKED_TOOLS = new Set([
   ...EXECUTION_STORAGE_TOOLS,
-  'create_issue',
-  'update_issue',
-  'plan_issue',
-  'append_task',
-  'split_task',
-  'supersede_task',
-  'set_task_dependencies',
-  'update_task',
-  'record_task_verification',
-  'accept_verified_task',
-  'publish_issue_to_github',
-  'refresh_github_issue',
-  'close_github_issue',
   'configure_github_plugin',
 ]);
 
@@ -372,6 +355,7 @@ export function createMcpToolContext(opts: McpServerOptions): MultiRepositoryMcp
     sessionId: opts.sessionId,
     principalId: opts.principalId,
     controllerType: opts.controllerType,
+    hostConversationSessionId: opts.hostConversationSessionId,
     controllerInstanceId: opts.controllerInstanceId,
     runtimeSourceRoot: opts.runtimeSourceRoot,
   };

package/adapters/mcp/oauth.ts

@@ -22,6 +22,19 @@ interface TokenData {
   clients?: Record<string, OAuthClientInformationFull>;
 }
 
+export interface McpOAuthClientRetirementResult {
+  clientId: string;
+  clientRemoved: boolean;
+  accessTokensRevoked: number;
+  refreshTokensRevoked: number;
+  orphanRefreshTokensPruned: number;
+  changed: boolean;
+}
+
+export interface McpOAuthProviderClientRetirementResult extends McpOAuthClientRetirementResult {
+  authorizationCodesRevoked: number;
+}
+
 function nowSeconds(): number {
   return Math.floor(Date.now() / 1000);
 }
@@ -129,6 +142,50 @@ export class McpOAuthTokenStore implements OAuthRegisteredClientsStore {
     return full;
   }
 
+  retireClient(clientId: string): McpOAuthClientRetirementResult {
+    const normalizedClientId = clientId.trim();
+    if (!normalizedClientId) throw new Error('MCP_OAUTH_CLIENT_ID_REQUIRED');
+
+    const ownedAccessTokens = new Set<string>();
+    for (const [token, info] of this.accessTokens) {
+      if (info.clientId === normalizedClientId) ownedAccessTokens.add(token);
+    }
+
+    let refreshTokensRevoked = 0;
+    let orphanRefreshTokensPruned = 0;
+    for (const [refreshToken, accessToken] of this.refreshTokens) {
+      if (ownedAccessTokens.has(accessToken)) {
+        this.refreshTokens.delete(refreshToken);
+        refreshTokensRevoked += 1;
+        continue;
+      }
+      if (!this.accessTokens.has(accessToken)) {
+        this.refreshTokens.delete(refreshToken);
+        orphanRefreshTokensPruned += 1;
+      }
+    }
+
+    let accessTokensRevoked = 0;
+    for (const token of ownedAccessTokens) {
+      if (this.accessTokens.delete(token)) accessTokensRevoked += 1;
+    }
+    const clientRemoved = this.clients.delete(normalizedClientId);
+    const changed = clientRemoved
+      || accessTokensRevoked > 0
+      || refreshTokensRevoked > 0
+      || orphanRefreshTokensPruned > 0;
+    if (changed) this.flush();
+
+    return {
+      clientId: normalizedClientId,
+      clientRemoved,
+      accessTokensRevoked,
+      refreshTokensRevoked,
+      orphanRefreshTokensPruned,
+      changed,
+    };
+  }
+
   getAccessToken(token: string): AuthInfo | undefined {
     return this.accessTokens.get(token);
   }
@@ -217,6 +274,7 @@ export interface McpOAuthAuthorizationCodeDiagnostics {
 
 export interface McpOAuthProvider extends OAuthServerProvider {
   authorizationCodeDiagnostics(): McpOAuthAuthorizationCodeDiagnostics;
+  retireClient(clientId: string): McpOAuthProviderClientRetirementResult;
 }
 
 export interface McpOAuthProviderOptions {
@@ -296,6 +354,21 @@ export function createMcpOAuthProvider(
       };
     },
 
+    retireClient(clientId: string): McpOAuthProviderClientRetirementResult {
+      const normalizedClientId = clientId.trim();
+      if (!normalizedClientId) throw new Error('MCP_OAUTH_CLIENT_ID_REQUIRED');
+      let authorizationCodesRevoked = 0;
+      for (const [code, pending] of authCodes) {
+        if (pending.clientId === normalizedClientId && authCodes.delete(code)) {
+          authorizationCodesRevoked += 1;
+        }
+      }
+      return {
+        ...store.retireClient(normalizedClientId),
+        authorizationCodesRevoked,
+      };
+    },
+
     get clientsStore(): OAuthRegisteredClientsStore {
       return store;
     },

package/adapters/mcp/paths.ts

@@ -1,5 +1,6 @@
 import { existsSync, lstatSync, realpathSync } from 'fs';
 import { dirname, isAbsolute, resolve, sep } from 'path';
+import { DEFAULT_PROJECT_ENGINEERING_CONTRACT_PATH } from '../../packages/kernel/work/api/index';
 import type { McpPathDecision, McpPathIntent, McpPolicy } from './types';
 
 function toPosixPath(value: string): string {
@@ -104,7 +105,9 @@ export function resolveMcpPath(
   if (!normalized.ok || !normalized.relativePath) return normalized;
 
   const relativePath = normalized.relativePath;
-  if (anyDenyGlobMatches(policy.denyGlobs, relativePath)) {
+  const isControllerProjectEngineeringContract = policy.profile === 'controller'
+    && relativePath === DEFAULT_PROJECT_ENGINEERING_CONTRACT_PATH;
+  if (!isControllerProjectEngineeringContract && anyDenyGlobMatches(policy.denyGlobs, relativePath)) {
     return { ok: false, relativePath, reason: `path is denied by MCP policy: ${relativePath}` };
   }