@moretea-labs/forge 1.6.0 → 1.7.0

package/src/runtime/control-plane/execution/work-terminal-cleanup.ts

@@ -8,14 +8,16 @@ import {
   writeFileSync,
 } from 'fs';
 import { dirname, join, resolve } from 'path';
-import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
+import { repoLocalNoIndexControllerHome, repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import {
   getRepository,
   listRepositories,
   selectRepositoryCheckout,
   setRepositoryCheckoutLifecycle,
 } from '../../../cli/repositories/registry';
+import { managedPathInside, managedWorktreeStorageRoot } from '../../../cli/repositories/worktree-storage';
 import { markRepositoryProjectionDirty } from '../../projections/invalidation';
+import { listControlPlaneRecords } from '../persistence/sqlite-store';
 import { getWorkContract } from '../facade/work-contract-store';
 import { getControllerSession, releaseControllerSession } from '../facade/controller-session-store';
 import { isRepositoryCompletionReceipt, isTerminalWorkContractStatus, type WorkContract } from '../facade/types';
@@ -30,6 +32,7 @@ import {
 import { getProcessRecord, listProcessRecords } from '../../execution/process-runtime/store';
 import {
   listWorkHandles,
+  readWorkHandle,
   transitionWorkHandle,
   writeWorkHandle,
   type WorkCleanupReceipt,
@@ -391,6 +394,42 @@ function selectTerminalCleanupTarget(repository: ReturnType<typeof getRepository
   return repository;
 }
 
+function isCurrentControllerManagedWorktree(
+  controllerHome: string,
+  worktreePath: string,
+): boolean {
+  try {
+    const storageRoot = managedWorktreeStorageRoot(
+      controllerHome,
+      listRepositories(controllerHome, { includeRemoved: true }),
+    );
+    if (managedPathInside(storageRoot, worktreePath)) return true;
+    // Older Controller releases used a namespaced sibling of controller/.
+    // Accept only namespaces whose source Home appears in this target's
+    // controlled migration receipt; then let the caller's Git common-dir,
+    // branch, cleanliness, and preservation checks prove the exact Work before
+    // any removal.
+    const sourceHomes = new Set<string>([resolve(controllerHome)]);
+    for (const record of listControlPlaneRecords<{ sourceHome?: unknown; status?: unknown }>(controllerHome, {
+      namespace: 'controller_home_migration',
+      limit: 1_000,
+    })) {
+      if (record.value.status !== 'applied' || typeof record.value.sourceHome !== 'string') continue;
+      const sourceHome = resolve(record.value.sourceHome);
+      sourceHomes.add(sourceHome);
+      const physical = repoLocalNoIndexControllerHome(sourceHome);
+      if (physical) sourceHomes.add(physical);
+    }
+    return [...sourceHomes].some((sourceHome) => {
+      const namespace = createHash('sha256').update(sourceHome).digest('hex').slice(0, 16);
+      const legacyRoot = join(dirname(resolve(controllerHome)), 'managed-worktrees', namespace);
+      return managedPathInside(legacyRoot, worktreePath);
+    });
+  } catch {
+    return false;
+  }
+}
+
 export interface TerminalWorkCleanupReconcileOptions {
   nowMs?: number;
   minAgeMs?: number;
@@ -417,11 +456,81 @@ function terminalOutcomeForContract(contract: WorkContract): WorkTerminalOutcome
   return 'failed';
 }
 
-function cleanupRetainedByRequest(contract: WorkContract, _handle: WorkHandleState): boolean {
+export function recoverTerminalWorkHandle(
+  controllerHome: string,
+  repositoryId: string,
+  workId: string,
+): WorkHandleState | undefined {
+  const existing = readWorkHandle(controllerHome, repositoryId, workId);
+  if (existing) return existing;
+  const contract = getWorkContract({ controllerHome, repoId: repositoryId }, workId);
+  if (!contract || !isTerminalWorkContractStatus(contract.status)) return undefined;
+  const worktreePath = contract.worktreeRef?.trim();
+  const checkoutId = contract.checkoutId?.trim();
+  if (!worktreePath || !checkoutId || !existsSync(worktreePath)) return undefined;
+  if (!isCurrentControllerManagedWorktree(controllerHome, worktreePath)) return undefined;
+
+  const repository = getRepository(repositoryId, controllerHome, { includeRemoved: true });
+  // Reconstruct physical cleanup authority from the recorded checkout entry itself.
+  // selectRepositoryCheckout returns a RepositoryRecord view rooted at a checkout,
+  // not the checkout entry (and terminal cleanup must also tolerate an already
+  // archived/removed registry lifecycle while the physical worktree still exists).
+  const checkout = repository.checkouts.find((candidate) => candidate.checkoutId === checkoutId);
+  if (!checkout || checkout.worktree !== true || resolve(checkout.canonicalRoot) !== resolve(worktreePath)) return undefined;
+  const branch = checkout.branch?.trim();
+  if (!branch) return undefined;
+
+  const head = git(worktreePath, ['rev-parse', 'HEAD']);
+  if (!head.ok || !head.stdout) return undefined;
+  const targetBranch = repository.defaultBranch || 'main';
+  const targetExists = branchExists(repository.canonicalRoot, targetBranch);
+  const contained = targetExists
+    ? git(repository.canonicalRoot, ['merge-base', '--is-ancestor', head.stdout, `refs/heads/${targetBranch}`]).ok
+    : false;
+  const delivered = contract.status === 'completed' && contained;
+  const session = getControllerSession({ controllerHome, repoId: repositoryId }, workId);
+  const recordedAt = nowIso();
+  return writeWorkHandle(controllerHome, {
+    schemaVersion: 1,
+    workId,
+    workContractId: workId,
+    sessionId: session?.sessionId ?? `terminal-recovery:${workId}`,
+    principalId: contract.principalId?.trim() || session?.principalId || 'terminal-recovery',
+    repositoryId,
+    checkoutId,
+    sourceCheckoutId: repository.activeCheckoutId,
+    worktreePath,
+    branch,
+    managedWorktree: true,
+    baseCommit: contract.baseRevision,
+    expectedHead: head.stdout,
+    permissionSnapshotVersion: 1,
+    state: delivered ? 'merged' : 'failed_terminal_cleanup',
+    failureReason: delivered ? undefined : 'Recovered terminal Work ownership for cleanup; target-branch containment was not proven.',
+    createdAt: contract.createdAt || recordedAt,
+    updatedAt: recordedAt,
+    cleanupResponsibility: { owner: 'work_finalizer', registeredAt: recordedAt },
+    finalization: {
+      validation: contract.status === 'failed' ? 'failed' : 'done',
+      commit: 'skipped',
+      merge: delivered ? 'done' : 'skipped',
+      branchCleanup: 'pending',
+      worktreeCleanup: 'pending',
+      ...(contract.status === 'failed' ? { lastError: 'Recovered failed terminal Work for cleanup.' } : {}),
+    },
+  });
+}
+
+function cleanupRetainedByRequest(contract: WorkContract, handle: WorkHandleState): boolean {
   // `skipped` in old WorkHandle finalization records was also used for legacy
   // no-op/error paths, so it is not sufficient proof of an explicit retention
-  // request. Only the completion receipt's dedicated maintenance warning is
-  // authoritative enough to suppress automatic reconciliation.
+  // request. New cancelled/terminal Work records persist an explicit physical
+  // resource disposition on the WorkHandle. Completed Work keeps the existing
+  // completion-receipt warning as the delivery authority.
+  if (
+    handle.terminalResourceDisposition?.mode === 'retained_by_request'
+    && handle.terminalResourceDisposition.retainWorktree === true
+  ) return true;
   const receipt = contract.completionReceipt;
   if (!receipt || !isRepositoryCompletionReceipt(receipt)) return false;
   return receipt.cleanup.warnings.some((warning) => warning.code === 'cleanup_retained_by_request');
@@ -588,7 +697,10 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
     current = persist(input.controllerHome, current, receipt);
     return { handle: current, receipt };
   }
-  if (!registeredPath && existsSync(current.worktreePath)) {
+  const migratedManagedWorktree = !registeredPath
+    && existsSync(current.worktreePath)
+    && isCurrentControllerManagedWorktree(input.controllerHome, current.worktreePath);
+  if (!registeredPath && existsSync(current.worktreePath) && !migratedManagedWorktree) {
     addBlocker(receipt, 'CHECKOUT_NOT_CONTROLLER_REGISTERED');
     current = persist(input.controllerHome, current, receipt);
     return { handle: current, receipt };
@@ -686,6 +798,9 @@ export async function cleanupTerminalWork(input: TerminalWorkCleanupInput): Prom
       addBlocker(receipt, `CHECKOUT_REGISTRY_REMOVE_FAILED: ${receipt.checkoutRegistry.reason}`);
     }
   }
+  if (!registeredPath && migratedManagedWorktree) {
+    receipt.checkoutRegistry.reason = 'Checkout metadata was absent after Controller Home migration; canonical managed-worktree and Git identity checks passed before cleanup.';
+  }
 
   if (!deleteBranch) {
     receipt.branchCleanup.status = 'retained';
@@ -789,8 +904,24 @@ export async function reconcileTerminalWorkCleanups(
   const repositories = listRepositories(controllerHome).filter((repository) => repository.enabled && !repository.removedAt);
   outer: for (const repository of repositories) {
     const handles = listWorkHandles(controllerHome, repository.repoId, 10_000)
-      .filter((handle) => handle.managedWorktree)
-      .sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
+      .filter((handle) => handle.managedWorktree);
+    const knownWorkIds = new Set(handles.map((handle) => handle.workId));
+    const recoveredWorkIds = new Set<string>();
+    for (const record of listControlPlaneRecords<WorkContract>(controllerHome, {
+      namespace: 'work_contract',
+      scope: repository.repoId,
+      limit: 10_000,
+    })) {
+      const contract = record.value;
+      if (knownWorkIds.has(contract.workId) || !isTerminalWorkContractStatus(contract.status)) continue;
+      if (!contract.worktreeRef?.trim() || !existsSync(contract.worktreeRef)) continue;
+      const recovered = recoverTerminalWorkHandle(controllerHome, repository.repoId, contract.workId);
+      if (!recovered) continue;
+      handles.push(recovered);
+      knownWorkIds.add(recovered.workId);
+      recoveredWorkIds.add(recovered.workId);
+    }
+    handles.sort((left, right) => left.updatedAt.localeCompare(right.updatedAt));
     for (const originalHandle of handles) {
       report.scanned += 1;
       const contract = getWorkContract({ controllerHome, repoId: repository.repoId }, originalHandle.workContractId ?? originalHandle.workId);
@@ -803,7 +934,11 @@ export async function reconcileTerminalWorkCleanups(
         report.skippedRetained.push(originalHandle.workId);
         continue;
       }
-      const terminalAt = Math.max(Date.parse(contract.updatedAt) || 0, Date.parse(originalHandle.updatedAt) || 0);
+      // Reconstructing a missing handle is metadata recovery, not new Work activity.
+      // Do not let that write reset the terminal-age grace period indefinitely.
+      const terminalAt = recoveredWorkIds.has(originalHandle.workId)
+        ? (Date.parse(contract.updatedAt) || 0)
+        : Math.max(Date.parse(contract.updatedAt) || 0, Date.parse(originalHandle.updatedAt) || 0);
       if (terminalAt > 0 && nowMs - terminalAt < minAgeMs) {
         report.skippedRecent.push(originalHandle.workId);
         continue;

package/src/runtime/control-plane/execution/work-validation-reconciler.ts

@@ -166,27 +166,35 @@ export function reconcileWorkValidation(
     }
 
     try {
-      const currentIdentity = record.checkExecution
-        ? controllerCheckExecutionIdentity(handle.worktreePath, checkId, record.checkExecution.timeoutMs)
-        : undefined;
+      if (binding.checkExecution && binding.checkExecution.checkId !== checkId) {
+        throw new Error(
+          `PROCESS_CHECK_RECEIPT_IDENTITY_MISMATCH: bound check ${binding.checkExecution.checkId} != ${checkId}`,
+        );
+      }
+      const expectedCheckExecution = binding.checkExecution
+        ?? (record.checkExecution
+          ? controllerCheckExecutionIdentity(handle.worktreePath, checkId, record.checkExecution.timeoutMs)
+          : undefined);
       const receipt = processCheckCompletionReceipt(record, {
         repoId: handle.repositoryId,
         checkoutId: handle.checkoutId,
         workId: handle.workId,
         checkId,
         processId: binding.processId,
-        ...(currentIdentity ? {
+        ...(expectedCheckExecution ? {
           checkExecution: {
-            cacheKey: currentIdentity.cacheKey,
-            revision: currentIdentity.revision,
-            definitionDigest: currentIdentity.definitionDigest,
-            environmentFingerprint: currentIdentity.environmentFingerprint,
-            timeoutMs: currentIdentity.timeoutMs,
-            scopeKey: processCheckSemanticScopeKey({
-              checkoutId: handle.checkoutId,
-              workId: handle.workId,
-              verificationBinding: { executionSessionId: handle.sessionId },
-            }, currentIdentity.reuseScope),
+            cacheKey: expectedCheckExecution.cacheKey,
+            revision: expectedCheckExecution.revision,
+            definitionDigest: expectedCheckExecution.definitionDigest,
+            environmentFingerprint: expectedCheckExecution.environmentFingerprint,
+            timeoutMs: expectedCheckExecution.timeoutMs,
+            scopeKey: binding.checkExecution
+              ? binding.checkExecution.scopeKey
+              : processCheckSemanticScopeKey({
+                  checkoutId: handle.checkoutId,
+                  workId: handle.workId,
+                  verificationBinding: { executionSessionId: handle.sessionId },
+                }, expectedCheckExecution.reuseScope),
           },
         } : {}),
       });

package/src/runtime/control-plane/execution/work-verification-snapshot.ts

@@ -5,7 +5,9 @@ import {
   lstatSync,
   mkdirSync,
   mkdtempSync,
+  readFileSync,
   readdirSync,
+  rmdirSync,
   rmSync,
   statSync,
   symlinkSync,
@@ -91,11 +93,28 @@ function cloneHead(sourceRoot: string, targetRoot: string, head: string): void {
   git(targetRoot, ['checkout', '--detach', '--quiet', head]);
 }
 
+function pruneEmptySnapshotParents(targetRoot: string, targetPath: string): void {
+  const boundary = resolve(targetRoot);
+  let current = dirname(resolve(targetPath));
+  while (current !== boundary) {
+    try {
+      if (readdirSync(current).length > 0) return;
+      rmdirSync(current);
+    } catch {
+      return;
+    }
+    current = dirname(current);
+  }
+}
+
 function overlayPath(sourceRoot: string, targetRoot: string, relativePath: string): void {
   const source = resolve(sourceRoot, relativePath);
   const target = resolve(targetRoot, relativePath);
   rmSync(target, { recursive: true, force: true });
-  if (!existsSync(source)) return;
+  if (!existsSync(source)) {
+    pruneEmptySnapshotParents(targetRoot, target);
+    return;
+  }
   mkdirSync(dirname(target), { recursive: true });
   const stat = lstatSync(source);
   if (stat.isSymbolicLink()) {
@@ -105,11 +124,69 @@ function overlayPath(sourceRoot: string, targetRoot: string, relativePath: strin
   cpSync(source, target, { recursive: stat.isDirectory(), dereference: false, force: true, preserveTimestamps: true });
 }
 
-function linkIgnoredNodeModules(sourceRoot: string, targetRoot: string): void {
-  const source = join(sourceRoot, 'node_modules');
+const DEPENDENCY_LOCK_FILES = ['bun.lock', 'bun.lockb', 'pnpm-lock.yaml', 'package-lock.json', 'yarn.lock'] as const;
+const DEPENDENCY_CONFIG_FILES = ['pnpm-workspace.yaml', 'bunfig.toml', '.npmrc', '.yarnrc.yml'] as const;
+const DEPENDENCY_METADATA_NAMES = ['package.json', ...DEPENDENCY_LOCK_FILES, ...DEPENDENCY_CONFIG_FILES] as const;
+
+function isDependencyMetadataPath(path: string): boolean {
+  const name = path.split('/').pop() ?? path;
+  return DEPENDENCY_METADATA_NAMES.some((candidate) => candidate === name);
+}
+
+function hasUntrackedDependencyMetadata(root: string): boolean {
+  return nulPaths(git(root, ['ls-files', '--others', '--exclude-standard', '-z'])).some(isDependencyMetadataPath);
+}
+
+function dependencyMetadataDigest(root: string): string | undefined {
+  if (!existsSync(join(root, 'package.json'))) return undefined;
+  const rootLock = DEPENDENCY_LOCK_FILES.find((name) => existsSync(join(root, name)));
+  if (!rootLock) return undefined;
+  const pathspecs = DEPENDENCY_METADATA_NAMES.flatMap((name) => [name, `:(glob)**/${name}`]);
+  const tracked = nulPaths(git(root, ['ls-files', '-z', '--', ...pathspecs]));
+  const files = [...new Set(tracked)].sort();
+  if (!files.includes('package.json') || !files.includes(rootLock)) return undefined;
+  const hash = createHash('sha256');
+  for (const path of files) {
+    hash.update(path);
+    hash.update('\0');
+    hash.update(readFileSync(join(root, path)));
+    hash.update('\0');
+  }
+  return hash.digest('hex');
+}
+
+function primaryWorktreeRoot(sourceRoot: string): string | undefined {
+  const commonDirValue = git(sourceRoot, ['rev-parse', '--git-common-dir']).toString('utf8').trim();
+  if (!commonDirValue) return undefined;
+  const commonDir = resolve(sourceRoot, commonDirValue);
+  const candidate = dirname(commonDir);
+  if (resolve(candidate) === resolve(sourceRoot)) return undefined;
+  if (!existsSync(join(candidate, '.git'))) return undefined;
+  return candidate;
+}
+
+function linkIgnoredNodeModules(sourceRoot: string, targetRoot: string, dirtyPaths: readonly string[]): void {
+  let source = join(sourceRoot, 'node_modules');
   const target = join(targetRoot, 'node_modules');
-  if (!existsSync(source) || existsSync(target)) return;
-  const ignored = spawnSync('git', ['-C', sourceRoot, 'check-ignore', '--quiet', '--', 'node_modules'], { stdio: 'ignore', timeout: 10_000 });
+  if (existsSync(target)) return;
+  if (!existsSync(source)) {
+    if (dirtyPaths.some(isDependencyMetadataPath)) return;
+    const primaryRoot = primaryWorktreeRoot(sourceRoot);
+    if (!primaryRoot) return;
+    const primaryNodeModules = join(primaryRoot, 'node_modules');
+    if (!existsSync(primaryNodeModules) || hasUntrackedDependencyMetadata(primaryRoot)) return;
+    const sourceDigest = dependencyMetadataDigest(sourceRoot);
+    const primaryDigest = dependencyMetadataDigest(primaryRoot);
+    if (!sourceDigest || sourceDigest !== primaryDigest) return;
+    source = primaryNodeModules;
+  }
+  // An existing managed-worktree node_modules may itself be a symlink. Git
+  // rejects child pathspecs through symlinks, while an absent node_modules
+  // needs a virtual child path so directory-only ignore rules still match.
+  const ignoreProbe = existsSync(join(sourceRoot, 'node_modules'))
+    ? 'node_modules'
+    : 'node_modules/.forge-verification-probe';
+  const ignored = spawnSync('git', ['-C', sourceRoot, 'check-ignore', '--quiet', '--', ignoreProbe], { stdio: 'ignore', timeout: 10_000 });
   if (ignored.status !== 0) return;
   try {
     symlinkSync(source, target, process.platform === 'win32' ? 'junction' : 'dir');
@@ -136,18 +213,18 @@ export function materializeWorkVerificationSnapshot(input: {
       excludedPaths.push(path);
       continue;
     }
-    if (input.scope.allowedPaths.length > 0 && matchesAny(input.scope.allowedPaths, path)) {
+    if (input.scope.allowedPaths.length === 0 || matchesAny(input.scope.allowedPaths, path)) {
       includedPaths.push(path);
       continue;
     }
-    throw new Error(`WORK_VERIFICATION_PATH_OWNERSHIP_AMBIGUOUS: ${path} is dirty but is neither allowed nor forbidden for ${input.scope.workId}`);
+    throw new Error(`WORK_VERIFICATION_PATH_OWNERSHIP_AMBIGUOUS: ${path} is dirty but is outside the allowed path fence for ${input.scope.workId}`);
   }
 
   const root = snapshotRoot(input.controllerHome, input.repoId, input.scope.workId);
   try {
     cloneHead(input.sourceRoot, root, sourceHead);
     for (const path of includedPaths) overlayPath(input.sourceRoot, root, path);
-    linkIgnoredNodeModules(input.sourceRoot, root);
+    linkIgnoredNodeModules(input.sourceRoot, root, dirtyPaths);
     const ownershipDigest = createHash('sha256').update(JSON.stringify({
       sourceHead,
       workId: input.scope.workId,

package/src/runtime/control-plane/facade/capability-registry.ts

@@ -1,5 +1,5 @@
 import type { AssistantPluginManifest } from '../../plugins/types';
-import type { CapabilityDescriptor, CapabilityDomain, CapabilityGroupSummary, CapabilityOperationClass, CapabilityRisk, FacadeTool } from './types';
+import type { CapabilityDescriptor, CapabilityDomain, CapabilityExecutionSurface, CapabilityGroupSummary, CapabilityOperationClass, CapabilityRisk, FacadeTool } from './types';
 
 const CORE_CAPABILITIES: CapabilityDescriptor[] = [
   {
@@ -83,24 +83,14 @@ const CORE_CAPABILITIES: CapabilityDescriptor[] = [
     summary: 'Diagnose and dry-run repair stuck jobs, stale projections, invalid check pollution, and worker unavailability without treating infrastructure failure as acceptance failure.',
   },
   {
-    capabilityId: 'controller.codex_delegation',
+    capabilityId: 'controller.external_controller',
     domain: 'controller',
     group: 'controller',
     operationClass: 'execute',
     risk: 'workspace_write',
     exposedVia: 'rh_work',
     schemaExposure: 'stable_static',
-    summary: 'Delegate bounded implementation work to Codex or Claude with context packs; workers return evidence and proposals but do not own final acceptance.',
-  },
-  {
-    capabilityId: 'controller.autonomous_goal_loop',
-    domain: 'controller',
-    group: 'controller',
-    operationClass: 'execute',
-    risk: 'workspace_write',
-    exposedVia: 'rh_work',
-    schemaExposure: 'stable_static',
-    summary: 'Advance daemon-owned goal contracts through deterministic policy, executor routing, verification, repair, and handoff.',
+    summary: 'Claim Work ownership and start an external Codex, Claude, or ChatGPT controller through controller_claim and launcher_start, with handoff decisions coordinated through rh_inbox; deprecated delegate is not an execution path.',
   },
   {
     capabilityId: 'controller.work_contract',
@@ -148,9 +138,9 @@ const CORE_CAPABILITIES: CapabilityDescriptor[] = [
     group: 'browser',
     operationClass: 'execute',
     risk: 'unknown',
-    exposedVia: 'rh_work',
+    exposedVia: 'plugin_action_execute',
     schemaExposure: 'stable_static',
-    summary: 'Use typed HTTP(S) browser navigation, snapshot, and interaction actions when browser capability is configured.',
+    summary: 'Use typed HTTP(S) browser navigation, snapshot, and interaction actions through plugin_action_execute when browser capability is configured.',
   },
   {
     capabilityId: 'platform.ios',
@@ -158,9 +148,9 @@ const CORE_CAPABILITIES: CapabilityDescriptor[] = [
     group: 'ios',
     operationClass: 'execute',
     risk: 'workspace_write',
-    exposedVia: 'rh_work',
+    exposedVia: 'plugin_action_execute',
     schemaExposure: 'stable_static',
-    summary: 'Use typed Xcode, simulator launch, screenshot, log, and smoke-test handlers when the local iOS toolchain is ready.',
+    summary: 'Use typed Xcode, simulator, screenshot, log, and smoke-review actions through plugin_action_execute when the local iOS toolchain is ready.',
   },
 ];
 
@@ -185,13 +175,16 @@ function domainFromPlugin(pluginId: string): CapabilityDomain {
   return 'plugin';
 }
 
-function exposedViaFromPluginAction(readOnly: boolean, risk: string): FacadeTool {
-  if (readOnly || risk === 'readonly') return 'rh_context';
-  return 'rh_work';
+function exposedViaFromPluginAction(_readOnly: boolean, _risk: string): CapabilityExecutionSurface {
+  // rh_context exposes schema/policy. plugin_action_execute is the sole action executor.
+  return 'plugin_action_execute';
 }
 
-export function pluginCapabilities(manifests: readonly AssistantPluginManifest[] = []): CapabilityDescriptor[] {
-  return manifests.flatMap((manifest) => manifest.actions.map((action) => ({
+function pluginCapabilityDescriptor(
+  manifest: AssistantPluginManifest,
+  action: AssistantPluginManifest['actions'][number],
+): CapabilityDescriptor {
+  return {
     capabilityId: `plugin.${manifest.pluginId}.${action.actionId}`,
     domain: domainFromPlugin(manifest.pluginId),
     group: manifest.pluginId === 'browser' ? 'browser' : 'plugin',
@@ -200,7 +193,11 @@ export function pluginCapabilities(manifests: readonly AssistantPluginManifest[]
     exposedVia: exposedViaFromPluginAction(action.readOnly, action.risk),
     schemaExposure: 'plugin_manifest',
     summary: `${manifest.displayName}: ${action.title}. ${action.description}`,
-  } satisfies CapabilityDescriptor)));
+  } satisfies CapabilityDescriptor;
+}
+
+export function pluginCapabilities(manifests: readonly AssistantPluginManifest[] = []): CapabilityDescriptor[] {
+  return manifests.flatMap((manifest) => manifest.actions.map((action) => pluginCapabilityDescriptor(manifest, action)));
 }
 
 export function listCapabilityDescriptors(manifests: readonly AssistantPluginManifest[] = []): CapabilityDescriptor[] {
@@ -209,6 +206,97 @@ export function listCapabilityDescriptors(manifests: readonly AssistantPluginMan
   return [...byId.values()].sort((a, b) => a.capabilityId.localeCompare(b.capabilityId));
 }
 
+export interface CapabilitySearchMatch {
+  capabilityId: string;
+  score: number;
+  matchedTerms: string[];
+  descriptor: CapabilityDescriptor;
+}
+
+function normalizedCapabilityText(value: string): string {
+  return value
+    .toLowerCase()
+    .replace(/[_./:-]+/g, ' ')
+    .replace(/[^a-z0-9]+/g, ' ')
+    .trim();
+}
+
+function capabilityIntentTokens(query: string): string[] {
+  return [...new Set(normalizedCapabilityText(query).split(' ').filter((token) => token.length >= 2))];
+}
+
+function intentBoosts(query: string, capabilityId: string): Array<{ label: string; score: number }> {
+  const normalized = normalizedCapabilityText(query);
+  const boosts: Array<{ label: string; score: number }> = [];
+  const appleDevelopmentIntent = /\b(xcode|provision|provisioning|signing|developer account|apple developer)\b/.test(normalized);
+  if (appleDevelopmentIntent) {
+    if (capabilityId === 'platform.ios') boosts.push({ label: 'apple-development', score: 90 });
+    if (capabilityId.startsWith('plugin.ios.')) boosts.push({ label: 'apple-development', score: 72 });
+    if (capabilityId === 'plugin.app_store_connect.auth_status') boosts.push({ label: 'apple-development', score: 88 });
+    else if (capabilityId === 'plugin.app_store_connect.configure') boosts.push({ label: 'apple-development', score: 82 });
+    else if (capabilityId.startsWith('plugin.app_store_connect.')) boosts.push({ label: 'apple-development', score: 28 });
+    if (capabilityId === 'plugin.desktop_operator.desktop_session_open') boosts.push({ label: 'xcode-desktop-fallback', score: 86 });
+    else if (capabilityId === 'plugin.desktop_operator.desktop_observe') boosts.push({ label: 'xcode-desktop-fallback', score: 78 });
+    else if (capabilityId === 'plugin.desktop_operator.desktop_press') boosts.push({ label: 'xcode-desktop-fallback', score: 74 });
+    else if (capabilityId.startsWith('plugin.desktop_operator.')) boosts.push({ label: 'xcode-desktop-fallback', score: 22 });
+  }
+
+  const browserLoginIntent = normalized.includes('browser')
+    && /\b(login|log in|signin|sign in|auth|authentication|session)\b/.test(normalized);
+  if (browserLoginIntent) {
+    if (capabilityId === 'plugin.browser') boosts.push({ label: 'browser-auth', score: 90 });
+    else if (capabilityId.startsWith('plugin.browser.')) boosts.push({ label: 'browser-auth', score: 62 });
+    if (capabilityId === 'plugin.desktop_operator.desktop_session_open') boosts.push({ label: 'browser-desktop-fallback', score: 70 });
+    else if (capabilityId === 'plugin.desktop_operator.desktop_observe') boosts.push({ label: 'browser-desktop-fallback', score: 62 });
+    else if (capabilityId.startsWith('plugin.desktop_operator.')) boosts.push({ label: 'browser-desktop-fallback', score: 18 });
+  }
+  return boosts;
+}
+
+export function searchCapabilityDescriptors(
+  query: string,
+  manifests: readonly AssistantPluginManifest[] = [],
+  limit = 12,
+): CapabilitySearchMatch[] {
+  const normalizedQuery = normalizedCapabilityText(query);
+  if (!normalizedQuery) return [];
+  const tokens = capabilityIntentTokens(query);
+  const boundedLimit = Math.max(1, Math.min(24, Math.floor(limit)));
+
+  return listCapabilityDescriptors(manifests)
+    .map((descriptor): CapabilitySearchMatch | undefined => {
+      const haystack = normalizedCapabilityText([
+        descriptor.capabilityId,
+        descriptor.summary,
+        descriptor.group,
+        descriptor.domain,
+        descriptor.operationClass,
+        descriptor.exposedVia,
+      ].join(' '));
+      let score = haystack.includes(normalizedQuery) ? 48 : 0;
+      const matchedTerms = new Set<string>();
+      for (const token of tokens) {
+        if (!haystack.includes(token)) continue;
+        matchedTerms.add(token);
+        score += descriptor.capabilityId.toLowerCase().includes(token) ? 12 : 5;
+      }
+      for (const boost of intentBoosts(query, descriptor.capabilityId)) {
+        score += boost.score;
+        matchedTerms.add(boost.label);
+      }
+      if (score <= 0) return undefined;
+      return {
+        capabilityId: descriptor.capabilityId,
+        score,
+        matchedTerms: [...matchedTerms].sort(),
+        descriptor,
+      };
+    })
+    .filter((entry): entry is CapabilitySearchMatch => Boolean(entry))
+    .sort((a, b) => b.score - a.score || a.capabilityId.localeCompare(b.capabilityId))
+    .slice(0, boundedLimit);
+}
+
 export function summarizeCapabilityGroups(manifests: readonly AssistantPluginManifest[] = []): CapabilityGroupSummary[] {
   const grouped = new Map<CapabilityDescriptor['group'], CapabilityDescriptor[]>();
   for (const descriptor of listCapabilityDescriptors(manifests)) {
@@ -222,7 +310,8 @@ export function summarizeCapabilityGroups(manifests: readonly AssistantPluginMan
       group,
       capabilityCount: entries.length,
       domains: [...new Set(entries.map((entry) => entry.domain))].sort(),
-      facadeTools: [...new Set(entries.map((entry) => entry.exposedVia))].sort(),
+      executionSurfaces: [...new Set(entries.map((entry) => entry.exposedVia))].sort(),
+      facadeTools: [...new Set(entries.map((entry) => entry.exposedVia).filter((surface): surface is FacadeTool => surface.startsWith('rh_')))].sort(),
       operationClasses: [...new Set(entries.map((entry) => entry.operationClass))].sort(),
       risks: [...new Set(entries.map((entry) => entry.risk))].sort(),
       schemaExposures: [...new Set(entries.map((entry) => entry.schemaExposure))].sort(),
@@ -257,6 +346,12 @@ export function getPluginActionCapabilitySchema(
         scopes: [...action.scopes],
         resourceClaims: structuredClone(action.resourceClaims),
         argumentsSchema: structuredClone(action.argumentsSchema),
+        authorizationReuse: action.confirmation === 'authorization'
+          ? {
+              mode: 'exact_target_persistent_when_adapter_supported',
+              hostPermissionBoundary: 'Tool invocation permission remains host-managed; reusable Forge grants never bypass strong_confirmation or destructive gates.',
+            }
+          : { mode: 'not_reusable' },
         executeWith: 'plugin_action_execute',
       };
     }
@@ -265,5 +360,14 @@ export function getPluginActionCapabilitySchema(
 }
 
 export function getCapabilityDescriptor(capabilityId: string, manifests: readonly AssistantPluginManifest[] = []): CapabilityDescriptor | undefined {
-  return listCapabilityDescriptors(manifests).find((descriptor) => descriptor.capabilityId === capabilityId);
+  const core = CORE_CAPABILITIES.find((descriptor) => descriptor.capabilityId === capabilityId);
+  if (core) return core;
+  for (const manifest of manifests) {
+    for (const action of manifest.actions) {
+      if (`plugin.${manifest.pluginId}.${action.actionId}` === capabilityId) {
+        return pluginCapabilityDescriptor(manifest, action);
+      }
+    }
+  }
+  return undefined;
 }