@moretea-labs/forge 1.8.0 → 1.8.2

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 } : {}),
   };
 }
 
@@ -192,6 +218,7 @@ interface ComputerSurfaceIndexReadyRecord {
   schemaVersion: 1;
   status: 'ready';
   indexedAt: string;
+  terminalBindingIndexReady?: true;
 }
 
 const COMPUTER_SURFACE_INDEX_READY_KEY = 'surface-index-v1-ready';
@@ -205,6 +232,18 @@ function surfaceBindingIndexKey(binding: ComputerSurfaceProviderBinding | undefi
   return `binding-${digest40(`${binding.providerId}:${binding.browserProduct ?? ''}:${binding.windowId}:${binding.tabId}`)}`;
 }
 
+// Migration-only negative evidence; never claims the live tab binding.
+function terminalBindingIndexKey(binding: ComputerSurfaceProviderBinding | undefined): string | undefined {
+  const key = surfaceBindingIndexKey(binding);
+  return key ? `terminal-${key}` : undefined;
+}
+
+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 +252,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 +264,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 +282,23 @@ 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;
+  const keys = surfaceIndexKeysForTarget(indexed);
+  const terminal = status === 'tombstoned' ? terminalBindingIndexKey(target.providerBinding) : undefined;
+  if (terminal) keys.push(terminal);
+  for (const key of keys) {
     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}`);
       }
@@ -267,20 +321,20 @@ function ensureSurfaceIndexes(transaction: ComputerTargetPersistenceTransaction)
     COMPUTER_TARGET_SCOPE,
     COMPUTER_SURFACE_INDEX_READY_KEY,
   );
-  if (ready?.value.status === 'ready') return;
+  if (ready?.value.status === 'ready' && ready.value.terminalBindingIndexReady === true) return;
   const surfaces = transaction.listAll<ComputerInteractionTargetEntry>({
     namespace: COMPUTER_TARGET_NAMESPACE,
     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,
     scope: COMPUTER_TARGET_SCOPE,
     key: COMPUTER_SURFACE_INDEX_READY_KEY,
     schemaVersion: 1,
-    value: { schemaVersion: 1, status: 'ready', indexedAt: now() } satisfies ComputerSurfaceIndexReadyRecord,
+    value: { schemaVersion: 1, status: 'ready', indexedAt: now(), terminalBindingIndexReady: true } satisfies ComputerSurfaceIndexReadyRecord,
     action: ready ? 'computer_surface_index_ready_repair' : 'computer_surface_index_ready',
     expectedRevision: ready?.revision ?? null,
   });
@@ -303,8 +357,12 @@ function readIndexedSurfaceRecord(
   const index = transaction.read<ComputerSurfaceIndexRecord>(COMPUTER_TARGET_INDEX_NAMESPACE, COMPUTER_TARGET_SCOPE, indexKey);
   if (!index) return undefined;
   const target = transaction.read<ComputerInteractionTargetEntry>(COMPUTER_TARGET_NAMESPACE, COMPUTER_TARGET_SCOPE, index.value.targetId);
-  if (target?.value.target.kind === 'surface'
-    && surfaceIndexKeysForTarget(normalizedSurfaceTarget(target.value.target)).includes(indexKey)) return target;
+  const surface = target?.value.target.kind === 'surface' ? normalizedSurfaceTarget(target.value.target) : undefined;
+  const valid = indexKey.startsWith('terminal-')
+    ? target?.value.status === 'tombstoned' && terminalBindingIndexKey(surface?.providerBinding) === indexKey
+    : (target?.value.status === 'active' || !indexKey.startsWith('binding-'))
+      && Boolean(surface && surfaceIndexKeysForTarget(surface).includes(indexKey));
+  if (target && valid) return target;
   transaction.delete({
     namespace: COMPUTER_TARGET_INDEX_NAMESPACE,
     scope: COMPUTER_TARGET_SCOPE,
@@ -318,8 +376,14 @@ function readIndexedSurfaceRecord(
 function deleteSurfaceIndexes(
   transaction: ComputerTargetPersistenceTransaction,
   target: ComputerSurfaceTarget,
+  status: 'active' | 'tombstoned' = 'active',
 ): void {
-  for (const key of surfaceIndexKeysForTarget(target)) {
+  const keys = surfaceIndexKeysForTarget(target);
+  if (status === 'tombstoned') {
+    const terminal = terminalBindingIndexKey(target.providerBinding);
+    if (terminal) keys.push(terminal);
+  }
+  for (const key of keys) {
     const index = transaction.read<ComputerSurfaceIndexRecord>(COMPUTER_TARGET_INDEX_NAMESPACE, COMPUTER_TARGET_SCOPE, key);
     if (!index || index.value.targetId !== target.targetId) continue;
     transaction.delete({
@@ -332,9 +396,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 +429,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 +440,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 +478,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 +491,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 +519,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,9 +623,18 @@ 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);
+      // An old repository's import is observation, not permission to revive a
+      // terminal physical tab. Current authoritative writes remain unaffected.
+      if (rawInput.reactivate === false) {
+        const terminalKey = terminalBindingIndexKey(providerBinding);
+        const terminal = terminalKey ? readIndexedSurfaceRecord(transaction, terminalKey) : undefined;
+        if (terminal?.value.status === 'tombstoned' && terminal.value.target.kind === 'surface') {
+          return { target: structuredClone(normalizedSurfaceTarget(terminal.value.target)), status: 'tombstoned', created: false };
+        }
+      }
       const indexed = new Map<string, ComputerTargetPersistenceRecord<ComputerInteractionTargetEntry>>();
       for (const indexKey of inputIndexKeys) {
         const candidate = readIndexedSurfaceRecord(transaction, indexKey);
@@ -562,11 +674,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 +697,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, existing.value.status);
       transaction.write({
         namespace: COMPUTER_TARGET_NAMESPACE,
         scope: COMPUTER_TARGET_SCOPE,
@@ -594,7 +717,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 +785,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 +882,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,
@@ -758,6 +897,7 @@ export function createComputerInteractionTargetAuthority(
         action: 'computer_surface_target_tombstone',
         expectedRevision: current.revision,
       });
+      writeSurfaceIndexes(transaction, normalizedSurfaceTarget(current.value.target), 'tombstoned');
       return true;
     });
   }
@@ -801,6 +941,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 +976,22 @@ 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,
+            });
+            writeSurfaceIndexes(transaction, normalizedSurfaceTarget(current.value.target), 'tombstoned');
           });
           return structuredClone(target);
         },
@@ -886,7 +1038,7 @@ export function createComputerInteractionTargetAuthority(
           const currentAtMs = Date.parse(current.value.tombstonedAt ?? current.updatedAt);
           const stillExpired = !Number.isFinite(currentAtMs) || nowMs - currentAtMs >= ttlMs;
           if (!stillExpired && !capacityEligible) return false;
-          if (current.value.target.kind === 'surface') deleteSurfaceIndexes(transaction, normalizedSurfaceTarget(current.value.target));
+          if (current.value.target.kind === 'surface') deleteSurfaceIndexes(transaction, normalizedSurfaceTarget(current.value.target), 'tombstoned');
           return transaction.delete({
             namespace: COMPUTER_TARGET_NAMESPACE,
             scope: COMPUTER_TARGET_SCOPE,
@@ -926,12 +1078,14 @@ export function createComputerInteractionTargetAuthority(
     create,
     get,
     require: requireTarget,
+    listAllApplications,
     withLease,
     createSurface,
     upsertSurface,
     getSurface,
     requireSurface,
     findSurfaceByAlias,
+    findSurfaceByStableIdentity,
     findSurfaceByProviderBinding,
     listSurfaces,
     listAllSurfaces,

package/adapters/mcp/access-mode.ts

@@ -6,12 +6,6 @@ import {
   type McpLocalConfig,
   writeMcpServiceLocalConfig,
 } from './auth';
-import type { McpToolset } from './types';
-import {
-  migrateControllerToolsetConfig,
-  normalizeConfiguredMcpToolset,
-  resolveControllerToolsetSelection,
-} from './toolset-selection';
 import {
   isAccessMode,
   type AccessMode,
@@ -20,28 +14,23 @@ import {
 export type ControllerAccessConfigSource =
   | 'controller_home.access_mode'
   | 'repo_local_fallback.access_mode'
-  | 'controller_home.legacy_toolset'
-  | 'repo_local_fallback.legacy_toolset'
   | 'default';
 
 export interface ControllerAccessState {
   configuredAccessMode: AccessMode;
   effectiveAccessMode: AccessMode;
-  /** Selected schema profile; access mode never changes this value. */
-  effectiveToolset: McpToolset;
+  /** The complete MCP capability registry is always available. */
+  effectiveToolset: 'full';
   source: ControllerAccessConfigSource;
   lastAppliedAt?: string;
   exposureRevision: number;
   configPathSource: 'controller_home' | 'repo_local_fallback' | 'default';
-  legacyToolset?: McpToolset;
   schemaStableAcrossAccessModes: true;
 }
 
 export interface ResolveControllerAccessStateInput {
   controllerHome: string;
   repoRoot?: string;
-  toolsetOverride?: McpToolset;
-  toolsetLocked?: boolean;
 }
 
 export interface PersistControllerAccessModeResult {
@@ -50,21 +39,22 @@ export interface PersistControllerAccessModeResult {
   state: ControllerAccessState;
 }
 
-export function accessModeForLegacyToolset(toolset: McpToolset): AccessMode {
-  return toolset === 'core' ? 'request' : 'full_access';
-}
-
-/** Retained for compatibility only; access mode no longer changes schema. */
-export function legacyToolsetForAccessMode(_mode: AccessMode): McpToolset {
-  return 'core';
-}
-
 function configLocation(controllerHome: string, repoRoot?: string): 'controller_home' | 'repo_local_fallback' | 'default' {
   if (existsSync(mcpControllerHomeLocalConfigPath(controllerHome))) return 'controller_home';
   if (repoRoot && existsSync(mcpLocalConfigPath(repoRoot))) return 'repo_local_fallback';
   return 'default';
 }
 
+/** One-way interpretation of old persisted permissions, not a toolset selector. */
+export function configuredControllerAccessMode(config: McpLocalConfig | null | undefined): AccessMode {
+  if (isAccessMode(config?.accessMode)) return config.accessMode;
+  // Historically, core without an explicit accessMode meant Request, not Full Access.
+  // Preserve that permission until the next canonical config write retires toolset.
+  return (config as { toolset?: unknown } | null | undefined)?.toolset === 'core'
+    ? 'request'
+    : 'full_access';
+}
+
 function normalizedRevision(value: unknown): number {
   if (typeof value !== 'number' || !Number.isFinite(value)) return 0;
   return Math.max(0, Math.trunc(value));
@@ -77,27 +67,18 @@ export function resolveControllerAccessState(input: ResolveControllerAccessState
     ? config.accessModeUpdatedAt
     : undefined;
   const exposureRevision = normalizedRevision(config?.accessModeRevision);
-  const rawLegacyToolset = normalizeConfiguredMcpToolset(config?.toolset);
-  const selectedToolset = resolveControllerToolsetSelection(config, input.toolsetOverride);
-  const configuredAccessMode = isAccessMode(config?.accessMode)
-    ? config.accessMode
-    : rawLegacyToolset
-      ? accessModeForLegacyToolset(rawLegacyToolset)
-      : 'full_access';
+  const configuredAccessMode = configuredControllerAccessMode(config);
   const source: ControllerAccessConfigSource = isAccessMode(config?.accessMode)
     ? (location === 'controller_home' ? 'controller_home.access_mode' : 'repo_local_fallback.access_mode')
-    : rawLegacyToolset
-      ? (location === 'controller_home' ? 'controller_home.legacy_toolset' : 'repo_local_fallback.legacy_toolset')
-      : 'default';
+    : 'default';
   return {
     configuredAccessMode,
     effectiveAccessMode: configuredAccessMode,
-    effectiveToolset: selectedToolset.toolset,
+    effectiveToolset: 'full',
     source,
     lastAppliedAt,
     exposureRevision,
     configPathSource: location,
-    legacyToolset: rawLegacyToolset,
     schemaStableAcrossAccessModes: true,
   };
 }
@@ -110,7 +91,6 @@ export function persistControllerAccessMode(
   const existing = loadMcpServiceLocalConfig(controllerHome, repoRoot) ?? {};
   const accessModeUpdatedAt = new Date().toISOString();
   const accessModeRevision = normalizedRevision(existing.accessModeRevision) + 1;
-  const migratedToolset = migrateControllerToolsetConfig(existing);
   const config: McpLocalConfig = {
     ...existing,
     version: Math.max(existing.version ?? 1, 2),
@@ -118,11 +98,10 @@ export function persistControllerAccessMode(
     accessMode: mode,
     accessModeUpdatedAt,
     accessModeRevision,
-    // Access changes preserve an explicit profile and migrate the old implicit
-    // Advanced label to Core; they never expand or shrink schema themselves.
-    toolset: migratedToolset.toolset,
-    toolsetExplicit: migratedToolset.toolsetExplicit,
   };
+  // Stored legacy profile values are not part of the one-surface contract.
+  delete (config as Record<string, unknown>).toolset;
+  delete (config as Record<string, unknown>).toolsetExplicit;
   const configPath = writeMcpServiceLocalConfig(controllerHome, config);
   return {
     configPath,

package/adapters/mcp/auth.ts

@@ -3,7 +3,6 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { resolveControllerHome } from '../../src/cli/repositories/controller-home';
 import type { AccessMode } from '../../src/runtime/control-plane/governance/access-policy';
-import type { McpToolset } from './types';
 
 export interface McpLocalConfig {
   version?: number;
@@ -29,9 +28,6 @@ export interface McpLocalConfig {
     localEndpoint?: string;
   };
   profile?: string;
-  toolset?: 'facade' | 'core' | 'advanced' | 'full';
-  /** Compatibility marker retained for previously persisted toolset choices. */
-  toolsetExplicit?: boolean;
   accessMode?: AccessMode;
   accessModeUpdatedAt?: string;
   accessModeRevision?: number;
@@ -46,7 +42,6 @@ export interface McpLocalConfig {
     mode?: 'standalone' | 'embedded' | 'remote' | 'disabled' | 'unknown';
     host?: string;
     port?: number;
-    autoOpen?: boolean;
   };
 }
 
@@ -91,10 +86,10 @@ export interface McpRuntimeState {
     forgeVersion?: string;
     toolSurfaceFingerprint?: string;
     runtimeToolSurfaceFingerprint?: string;
-    toolset?: 'facade' | 'core' | 'advanced' | 'full';
+    toolset?: 'full';
     configuredAccessMode?: AccessMode;
     effectiveAccessMode?: AccessMode;
-    effectiveToolset?: McpToolset;
+    effectiveToolset?: 'full';
     accessModeSource?: string;
     accessModeLastAppliedAt?: string;
     exposureRevision?: number;

package/adapters/mcp/instructions.ts

@@ -2,22 +2,23 @@ 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, the model selects rh_context semantic retrieval, execute_command terminal search, or exact file reads according to the evidence required; no mandatory retrieval router or tool sequence is imposed. If rh_context is used, follow with exact paths, symbols, tests, relationships, or impact domains only when that materially improves 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. ChatGPT chooses semantic source retrieval or direct terminal search according to what the task actually requires; Forge does not rank tools as a workflow policy. The low-level search_repository handler is an internal compatibility surface. Use execute_command 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.',
-      'repository_safe_patch_apply returns bounded edit-session diff evidence for semantic review. Review that evidence directly instead of issuing a mandatory follow-up diff/status call; expand it only when truncated or semantically ambiguous. Its typed operation contract is strict: use type=create only for a path that does not exist, and use write/replace/insert/prepend/append/delete only for existing targets; never reinterpret a missing write target as create. Whole-file source replacement is valid when it is an explicit scoped write against the exact expected file SHA/fingerprint; stale-source and dirty-ownership fences must remain authoritative. Do not bypass those fences with arbitrary shell redirection merely because a deterministic rewrite is convenient. After a bounded successful change, finish the requested delivery directly. Avoid additional investigation whose result cannot change implementation or acceptance, and do not invoke hidden atomic compatibility tools merely because they exist in the full profile.',
+      'repository_safe_patch_apply returns bounded edit-session diff evidence for semantic review. Review that evidence directly instead of issuing a mandatory follow-up diff/status call; expand it only when truncated or semantically ambiguous. Its typed operation contract is strict: use type=create only for a path that does not exist, and use write/replace/insert/prepend/append/delete only for existing targets; never reinterpret a missing write target as create. Whole-file source replacement is valid when it is an explicit scoped write against the exact expected file SHA/fingerprint; stale-source and dirty-ownership fences must remain authoritative. Do not bypass those fences with arbitrary shell redirection merely because a deterministic rewrite is convenient. After a bounded successful change, finish the requested delivery directly. Avoid additional investigation whose result cannot change implementation or acceptance, and do not invoke redundant atomic compatibility tools merely because they remain registered.',
     ].join(' ');
   }
   if (profile === 'orchestrator') {