@moretea-labs/forge 1.7.2 → 1.8.0

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

@@ -1,5 +1,6 @@
 import { createHash } from 'crypto';
 import {
+  chmodSync,
   cpSync,
   existsSync,
   lstatSync,
@@ -7,19 +8,22 @@ import {
   mkdtempSync,
   readFileSync,
   readdirSync,
+  realpathSync,
   rmdirSync,
   rmSync,
   statSync,
   symlinkSync,
   writeFileSync,
 } from 'fs';
-import { dirname, join, resolve } from 'path';
+import { dirname, join, resolve, sep } from 'path';
 import { spawnSync } from 'child_process';
 import { repositoryControllerRoot } from '../../../cli/repositories/controller-home';
 import { globMatches, normalizeMcpRelativePath } from '../../../cli/mcp/paths';
 import { sanitizeFileComponent } from '../../shared/json-files';
+import { measureReclaimablePath, RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION } from '../lifecycle-retention-metrics';
 
-const STALE_SNAPSHOT_MS = 6 * 60 * 60_000;
+export const WORK_VERIFICATION_SNAPSHOT_RETENTION_MS = 6 * 60 * 60_000;
+export const UNMARKED_WORK_VERIFICATION_SNAPSHOT_RETENTION_MS = 24 * 60 * 60_000;
 const SNAPSHOT_MARKER = '.ai/harness/controller/work-verification-snapshot.json';
 
 export interface WorkVerificationSnapshotScope {
@@ -66,20 +70,115 @@ function matchesAny(patterns: readonly string[], path: string): boolean {
   return patterns.some((pattern) => globMatches(pattern, path));
 }
 
-function snapshotRoot(controllerHome: string, repoId: string, workId: string): string {
+export interface WorkVerificationSnapshotRetentionOptions {
+  nowMs?: number;
+  protectedWorkIds?: readonly string[];
+  maxEntries?: number;
+  maxRemovals?: number;
+}
+
+export interface WorkVerificationSnapshotRetentionReport {
+  policyVersion: typeof RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION;
+  inspected: number;
+  eligible: number;
+  attempted: number;
+  removedPaths: string[];
+  reclaimedBytes: number;
+  unknownReclaimedByteCount: number;
+  retained: number;
+  protected: number;
+  skippedByReason: Record<string, number>;
+  errors: string[];
+  truncated: boolean;
+  budgetExhausted: boolean;
+}
+
+type SnapshotOwner = { state: 'marked'; workId: string } | { state: 'missing' } | { state: 'invalid' };
+
+function snapshotOwner(path: string): SnapshotOwner {
+  const marker = join(path, SNAPSHOT_MARKER);
+  if (!existsSync(marker)) return { state: 'missing' };
+  try {
+    const parsed = JSON.parse(readFileSync(marker, 'utf8')) as { workId?: unknown };
+    return typeof parsed.workId === 'string' && parsed.workId.trim()
+      ? { state: 'marked', workId: parsed.workId.trim() }
+      : { state: 'invalid' };
+  } catch {
+    return { state: 'invalid' };
+  }
+}
+
+/**
+ * Reclaim stale verification snapshots without becoming a Work authority.
+ * Active Work ids are caller-supplied from the canonical Work store. Missing
+ * markers receive a longer grace because a snapshot is unmarked while it is
+ * still being materialized; malformed markers fail closed for recovery review.
+ */
+export function cleanupStaleWorkVerificationSnapshots(
+  controllerHome: string,
+  repoId: string,
+  options: WorkVerificationSnapshotRetentionOptions = {},
+): WorkVerificationSnapshotRetentionReport {
   const root = join(repositoryControllerRoot(controllerHome, repoId), 'verification-snapshots');
-  mkdirSync(root, { recursive: true });
-  const now = Date.now();
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
+  const maxEntries = Math.max(1, Math.floor(options.maxEntries ?? 512));
+  const maxRemovals = Math.max(1, Math.floor(options.maxRemovals ?? 50));
+  const nowMs = options.nowMs ?? Date.now();
+  const protectedWorkIds = new Set(options.protectedWorkIds ?? []);
+  const report: WorkVerificationSnapshotRetentionReport = {
+    policyVersion: RUNTIME_LIFECYCLE_RETENTION_POLICY_VERSION,
+    inspected: 0, eligible: 0, attempted: 0, removedPaths: [], reclaimedBytes: 0,
+    unknownReclaimedByteCount: 0, retained: 0, protected: 0, skippedByReason: {},
+    errors: [], truncated: false, budgetExhausted: false,
+  };
+  const skip = (reason: string): void => { report.skippedByReason[reason] = (report.skippedByReason[reason] ?? 0) + 1; };
+  if (!existsSync(root)) return report;
+  let entries;
+  try { entries = readdirSync(root, { withFileTypes: true }); } catch (error) {
+    report.errors.push(`verification snapshot root: ${error instanceof Error ? error.message : String(error)}`);
+    return report;
+  }
+  for (const entry of entries) {
     if (!entry.isDirectory() || !entry.name.startsWith('snapshot-')) continue;
+    if (report.inspected >= maxEntries) { report.truncated = true; skip('scan_budget_exhausted'); break; }
+    report.inspected += 1;
     const path = join(root, entry.name);
+    let ageMs: number;
+    try { ageMs = Math.max(0, nowMs - statSync(path).mtimeMs); } catch (error) {
+      report.errors.push(`${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
+      continue;
+    }
+    const owner = snapshotOwner(path);
+    if (owner.state === 'invalid') { report.retained += 1; skip('invalid_marker'); continue; }
+    if (owner.state === 'marked' && protectedWorkIds.has(owner.workId)) {
+      report.retained += 1; report.protected += 1; skip('active_work'); continue;
+    }
+    const retentionMs = owner.state === 'missing'
+      ? UNMARKED_WORK_VERIFICATION_SNAPSHOT_RETENTION_MS
+      : WORK_VERIFICATION_SNAPSHOT_RETENTION_MS;
+    if (ageMs <= retentionMs) { report.retained += 1; skip('ttl_not_expired'); continue; }
+    report.eligible += 1;
+    if (report.attempted >= maxRemovals) { report.retained += 1; report.budgetExhausted = true; skip('cleanup_budget_exhausted'); continue; }
+    report.attempted += 1;
+    const measurement = measureReclaimablePath(path);
     try {
-      if (now - statSync(path).mtimeMs > STALE_SNAPSHOT_MS) rmSync(path, { recursive: true, force: true });
-    } catch {
-      // Best-effort stale cleanup; a fresh snapshot must not fail because an old
-      // directory disappeared concurrently.
+      rmSync(path, { recursive: true, force: true });
+      report.removedPaths.push(entry.name);
+      if (measurement.complete) report.reclaimedBytes += measurement.bytes;
+      else report.unknownReclaimedByteCount += 1;
+    } catch (error) {
+      report.errors.push(`${entry.name}: ${error instanceof Error ? error.message : String(error)}`);
     }
   }
+  report.removedPaths.sort();
+  report.errors.sort();
+  return report;
+}
+
+function snapshotRoot(controllerHome: string, repoId: string, workId: string): string {
+  const root = join(repositoryControllerRoot(controllerHome, repoId), 'verification-snapshots');
+  mkdirSync(root, { recursive: true });
+  // Retention is centralized in Runtime maintenance. Snapshot creation must not
+  // opportunistically delete another Work's verification evidence.
   return mkdtempSync(join(root, `snapshot-${sanitizeFileComponent(workId).slice(0, 48)}-`));
 }
 
@@ -95,6 +194,27 @@ function cloneHead(sourceRoot: string, targetRoot: string, head: string): void {
   git(targetRoot, ['checkout', '--detach', '--quiet', head]);
 }
 
+function normalizeTrackedSnapshotModes(sourceRoot: string, targetRoot: string): void {
+  for (const relativePath of nulPaths(git(sourceRoot, ['ls-files', '-z']))) {
+    const source = resolve(sourceRoot, relativePath);
+    const target = resolve(targetRoot, relativePath);
+    try {
+      const sourceStat = lstatSync(source);
+      const targetStat = lstatSync(target);
+      if (!sourceStat.isFile() || !targetStat.isFile()) continue;
+      // Git tracks only the executable bit for regular files. A checkout
+      // created under umask=0002 otherwise materializes 0664/0775 and makes
+      // exact-mode gates depend on the Runtime process umask. Canonicalize the
+      // untracked permission bits while preserving the Work's current
+      // executable semantics (including an uncommitted chmod +/-x).
+      chmodSync(target, (sourceStat.mode & 0o111) !== 0 ? 0o755 : 0o644);
+    } catch {
+      // Deleted paths, symlinks, and concurrently disappearing files are
+      // handled by the normal overlay/deletion path and are not regular files.
+    }
+  }
+}
+
 function pruneEmptySnapshotParents(targetRoot: string, targetPath: string): void {
   const boundary = resolve(targetRoot);
   let current = dirname(resolve(targetPath));
@@ -167,6 +287,51 @@ function primaryWorktreeRoot(sourceRoot: string): string | undefined {
   return candidate;
 }
 
+function isManagedWorktreeDependencyLink(sourceRoot: string, path: string): boolean {
+  if (path !== 'node_modules') return false;
+  const candidate = join(sourceRoot, path);
+  try {
+    if (!lstatSync(candidate).isSymbolicLink()) return false;
+    const primaryRoot = primaryWorktreeRoot(sourceRoot);
+    if (!primaryRoot) return false;
+    const primaryNodeModules = join(primaryRoot, 'node_modules');
+    if (!existsSync(primaryNodeModules)) return false;
+    return realpathSync(candidate) === realpathSync(primaryNodeModules);
+  } catch {
+    return false;
+  }
+}
+
+function isControllerHomeRuntimeBindingLink(
+  sourceRoot: string,
+  controllerHome: string,
+  repoId: string,
+  path: string,
+): boolean {
+  if (!path.startsWith('.ai/harness/') && !path.startsWith('.forge/')) return false;
+  const candidate = join(sourceRoot, path);
+  try {
+    if (!lstatSync(candidate).isSymbolicLink()) return false;
+    const controllerRoot = realpathSync(repositoryControllerRoot(controllerHome, repoId));
+    const target = realpathSync(candidate);
+    return target === controllerRoot || target.startsWith(`${controllerRoot}${sep}`);
+  } catch {
+    return false;
+  }
+}
+
+function excludeSyntheticSnapshotPath(targetRoot: string, path: string): void {
+  const rawExcludePath = git(targetRoot, ['rev-parse', '--git-path', 'info/exclude']).toString('utf8').trim();
+  if (!rawExcludePath) throw new Error('WORK_VERIFICATION_SNAPSHOT_EXCLUDE_PATH_UNAVAILABLE');
+  const excludePath = resolve(targetRoot, rawExcludePath);
+  const existing = existsSync(excludePath) ? readFileSync(excludePath, 'utf8') : '';
+  const entries = existing.split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean);
+  if (entries.includes(path)) return;
+  mkdirSync(dirname(excludePath), { recursive: true });
+  const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+  writeFileSync(excludePath, `${existing}${separator}${path}\n`);
+}
+
 function linkIgnoredNodeModules(sourceRoot: string, targetRoot: string, dirtyPaths: readonly string[]): void {
   let source = join(sourceRoot, 'node_modules');
   const target = join(targetRoot, 'node_modules');
@@ -185,16 +350,30 @@ function linkIgnoredNodeModules(sourceRoot: string, targetRoot: string, dirtyPat
   // 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 managedDependencyLink = isManagedWorktreeDependencyLink(sourceRoot, 'node_modules');
   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;
+  const ignored = managedDependencyLink
+    ? true
+    : spawnSync('git', ['-C', sourceRoot, 'check-ignore', '--quiet', '--', ignoreProbe], { stdio: 'ignore', timeout: 10_000 }).status === 0;
+  if (!ignored) return;
   try {
     symlinkSync(source, target, process.platform === 'win32' ? 'junction' : 'dir');
+    // Preserve the source checkout's exact Git-visible input identity. A normal
+    // ignored node_modules directory is not an input, while a pre-existing managed
+    // worktree dependency link is currently Git-visible as an untracked symlink.
+    // Snapshot materialization must not change either case merely because it uses
+    // the same dependency cache through a link.
+    const sourceDependencyLinkVisible = nulPaths(git(sourceRoot, [
+      'ls-files', '--others', '--exclude-standard', '-z', '--', 'node_modules',
+    ])).includes('node_modules');
+    if (!sourceDependencyLinkVisible) excludeSyntheticSnapshotPath(targetRoot, 'node_modules');
   } catch {
-    // Dependency linking is an optimization. If it is unavailable the check may
-    // still succeed using its own toolchain resolution; never copy a huge cache.
+    // Dependency linking is an optimization. If either the link or its local Git
+    // exclusion cannot be established coherently, remove the partial link rather
+    // than letting snapshot-only state contaminate Check identity.
+    rmSync(target, { recursive: true, force: true });
   }
 }
 
@@ -206,7 +385,9 @@ export function materializeWorkVerificationSnapshot(input: {
 }): WorkVerificationSnapshot {
   const sourceHead = git(input.sourceRoot, ['rev-parse', '--verify', 'HEAD']).toString('utf8').trim();
   const tracked = nulPaths(git(input.sourceRoot, ['diff', '--name-only', '-z', 'HEAD', '--']));
-  const untracked = nulPaths(git(input.sourceRoot, ['ls-files', '--others', '--exclude-standard', '-z']));
+  const untracked = nulPaths(git(input.sourceRoot, ['ls-files', '--others', '--exclude-standard', '-z']))
+    .filter((path) => !isManagedWorktreeDependencyLink(input.sourceRoot, path))
+    .filter((path) => !isControllerHomeRuntimeBindingLink(input.sourceRoot, input.controllerHome, input.repoId, path));
   const dirtyPaths = [...new Set([...tracked, ...untracked])].sort();
   const includedPaths: string[] = [];
   const excludedPaths: string[] = [];
@@ -225,7 +406,11 @@ export function materializeWorkVerificationSnapshot(input: {
   const root = snapshotRoot(input.controllerHome, input.repoId, input.scope.workId);
   try {
     cloneHead(input.sourceRoot, root, sourceHead);
+    normalizeTrackedSnapshotModes(input.sourceRoot, root);
     for (const path of includedPaths) overlayPath(input.sourceRoot, root, path);
+    // Overlay copies may reintroduce umask-derived group-write bits from the
+    // source Worktree, so normalize tracked regular files again afterwards.
+    normalizeTrackedSnapshotModes(input.sourceRoot, root);
     linkIgnoredNodeModules(input.sourceRoot, root, dirtyPaths);
     const ownershipDigest = createHash('sha256').update(JSON.stringify({
       sourceHead,

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

@@ -1,3 +1,8 @@
+import {
+  COMPUTER_CAPTURE_CAPABILITY,
+  COMPUTER_INPUT_CAPABILITY,
+  COMPUTER_OBSERVE_CAPABILITY,
+} from '../../../../packages/protocols/computer/index';
 import type { AssistantPluginManifest } from '../../plugins/types';
 import type { CapabilityDescriptor, CapabilityDomain, CapabilityExecutionSurface, CapabilityGroupSummary, CapabilityOperationClass, CapabilityRisk, FacadeTool } from './types';
 
@@ -100,7 +105,7 @@ const CORE_CAPABILITIES: CapabilityDescriptor[] = [
     risk: 'workspace_write',
     exposedVia: 'rh_work',
     schemaExposure: 'stable_static',
-    summary: 'Persist and advance WorkContract records for goal workloop start, continue, verify, finalize, and stop.',
+    summary: 'Persist and advance WorkContract records for goal workloop start, continue, verify, explicit implementation review, finalize, and stop.',
   },
   {
     capabilityId: 'controller.plan_contract',
@@ -184,6 +189,10 @@ function pluginCapabilityDescriptor(
   manifest: AssistantPluginManifest,
   action: AssistantPluginManifest['actions'][number],
 ): CapabilityDescriptor {
+  const semanticCapabilities = (manifest.capabilities ?? [])
+    .filter((capability) => capability.actions.includes(action.actionId))
+    .map((capability) => capability.capabilityId)
+    .sort();
   return {
     capabilityId: `plugin.${manifest.pluginId}.${action.actionId}`,
     domain: domainFromPlugin(manifest.pluginId),
@@ -193,6 +202,7 @@ function pluginCapabilityDescriptor(
     exposedVia: exposedViaFromPluginAction(action.readOnly, action.risk),
     schemaExposure: 'plugin_manifest',
     summary: `${manifest.displayName}: ${action.title}. ${action.description}`,
+    ...(semanticCapabilities.length > 0 ? { semanticCapabilities } : {}),
   } satisfies CapabilityDescriptor;
 }
 
@@ -225,8 +235,10 @@ 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 }> {
+function intentBoosts(query: string, descriptor: CapabilityDescriptor): Array<{ label: string; score: number }> {
   const normalized = normalizedCapabilityText(query);
+  const capabilityId = descriptor.capabilityId;
+  const semanticCapabilities = new Set(descriptor.semanticCapabilities ?? []);
   const boosts: Array<{ label: string; score: number }> = [];
   const appleDevelopmentIntent = /\b(xcode|provision|provisioning|signing|developer account|apple developer)\b/.test(normalized);
   if (appleDevelopmentIntent) {
@@ -235,10 +247,9 @@ function intentBoosts(query: string, capabilityId: string): Array<{ label: strin
     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 });
+    if (semanticCapabilities.has(COMPUTER_OBSERVE_CAPABILITY)) boosts.push({ label: 'xcode-computer-observe', score: 78 });
+    if (semanticCapabilities.has(COMPUTER_INPUT_CAPABILITY)) boosts.push({ label: 'xcode-computer-input', score: 74 });
+    if (semanticCapabilities.has(COMPUTER_CAPTURE_CAPABILITY)) boosts.push({ label: 'xcode-computer-capture', score: 44 });
   }
 
   const browserLoginIntent = normalized.includes('browser')
@@ -246,9 +257,8 @@ function intentBoosts(query: string, capabilityId: string): Array<{ label: strin
   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 });
+    if (semanticCapabilities.has(COMPUTER_OBSERVE_CAPABILITY)) boosts.push({ label: 'browser-computer-observe', score: 54 });
+    if (semanticCapabilities.has(COMPUTER_INPUT_CAPABILITY)) boosts.push({ label: 'browser-computer-input', score: 50 });
   }
   return boosts;
 }
@@ -272,6 +282,7 @@ export function searchCapabilityDescriptors(
         descriptor.domain,
         descriptor.operationClass,
         descriptor.exposedVia,
+        ...(descriptor.semanticCapabilities ?? []),
       ].join(' '));
       let score = haystack.includes(normalizedQuery) ? 48 : 0;
       const matchedTerms = new Set<string>();
@@ -280,7 +291,7 @@ export function searchCapabilityDescriptors(
         matchedTerms.add(token);
         score += descriptor.capabilityId.toLowerCase().includes(token) ? 12 : 5;
       }
-      for (const boost of intentBoosts(query, descriptor.capabilityId)) {
+      for (const boost of intentBoosts(query, descriptor)) {
         score += boost.score;
         matchedTerms.add(boost.label);
       }