@moretea-labs/forge 1.5.0-rc.1 → 1.5.0

package/src/cli/mcp/tool-capability-cache.ts

@@ -22,7 +22,7 @@ export function controllerCapabilityGroupForTool(name: string): ControllerCapabi
   if (name.startsWith('plugin_') || name === 'list_plugins') return 'plugins';
   if (name.startsWith('runtime_') || name.startsWith('controller_')) return 'runtime';
   if (name.startsWith('work_') || name.startsWith('session_') || name.startsWith('approval_') || name.startsWith('result_')) return 'workflow';
-  if (name.startsWith('admin_') || name.startsWith('campaign_')) return 'admin';
+  if (name.startsWith('admin_')) return 'admin';
   return 'legacy';
 }
 

package/src/cli/mcp/toolset-names.ts

@@ -6,7 +6,7 @@ export const PREFERRED_FACADE_TOOL_NAMES = [...FACADE_TOOLS] as const;
 /**
  * Default ChatGPT-facing MCP surface. The Runtime keeps every internal atomic
  * handler and the full compatibility profile; ChatGPT only needs this bounded
- * execution surface. Atomic Git / issue-task / campaign / edit-session / plugin
+ * execution surface. Atomic Git / issue-task / edit-session / plugin
  * tools remain registered and reachable through `toolset=full`.
  */
 export const DEFAULT_CONTROLLER_TOOL_NAMES = [

package/src/cli/mcp/toolset.ts

@@ -213,7 +213,6 @@ function staticControllerExposureSnapshot(
 function capabilityForToolName(name: string): string {
   if (name.startsWith('rh_')) return 'facade';
   if (name.startsWith('git_') || name.startsWith('repository_git_')) return 'git';
-  if (name.includes('campaign')) return 'campaign';
   if (/(^|_)(issue|task|project|worklog)(_|$)/.test(name)) return 'issue-task';
   if (name.startsWith('repository_') || name.startsWith('search_') || name.startsWith('read_')) return 'repository';
   if (name.startsWith('ios_')) return 'ios';

package/src/cli/mcp/transports/http.ts

@@ -162,6 +162,18 @@ export function mcpSessionToolSurfaceFingerprintIsCurrent(
   return !sessionFingerprint || !currentFingerprint || sessionFingerprint === currentFingerprint;
 }
 
+export async function resolveMcpSessionCurrentFingerprint(
+  publishedFingerprint: string | undefined,
+  loadRuntimeFingerprint?: () => Promise<string | undefined>,
+): Promise<string | undefined> {
+  // Runtime status publishes the exact schema fingerprint observed at session
+  // initialization/cutover. Prefer that O(1) fence on the hot path. If the
+  // publication is temporarily unavailable, retain the previous fail-safe
+  // behavior by asking the Canonical Runtime directly.
+  if (publishedFingerprint) return publishedFingerprint;
+  return await loadRuntimeFingerprint?.();
+}
+
 function toolCallOutsideSessionSchema(body: unknown, toolNames: readonly string[] | undefined): boolean {
   if (!toolNames) return false;
   const messages = Array.isArray(body) ? body : [body];
@@ -744,8 +756,12 @@ async function handleMcpPost(
       registry.beginPost(sessionId);
       stats.activePosts += 1;
       try {
-        const runtimeSchema = await resolveRuntimeSchema?.(managed.toolContext);
-        const currentFingerprint = runtimeSchema?.fingerprint ?? currentToolSurfaceFingerprint();
+        const currentFingerprint = await resolveMcpSessionCurrentFingerprint(
+          currentToolSurfaceFingerprint(),
+          resolveRuntimeSchema
+            ? async () => (await resolveRuntimeSchema(managed.toolContext))?.fingerprint
+            : undefined,
+        );
         if (!mcpSessionToolSurfaceFingerprintIsCurrent(managed.toolSurfaceFingerprint, currentFingerprint)) {
           // Keep the transport/session alive long enough for the host to observe
           // the recoverable reset and issue a replacement initialize request.
@@ -795,8 +811,12 @@ async function handleMcpGet(
   req.once('aborted', releaseStream);
   res.once('close', releaseStream);
   try {
-    const runtimeSchema = await resolveRuntimeSchema?.(managed.toolContext);
-    const currentFingerprint = runtimeSchema?.fingerprint ?? currentToolSurfaceFingerprint();
+    const currentFingerprint = await resolveMcpSessionCurrentFingerprint(
+      currentToolSurfaceFingerprint(),
+      resolveRuntimeSchema
+        ? async () => (await resolveRuntimeSchema(managed.toolContext))?.fingerprint
+        : undefined,
+    );
     if (!mcpSessionToolSurfaceFingerprintIsCurrent(managed.toolSurfaceFingerprint, currentFingerprint)) {
       // Preserve the existing SSE transport while asking the host to
       // reinitialize. The replacement initialize owns supersession/cleanup.

package/src/cli/repositories/branch-name-policy.ts

@@ -48,10 +48,3 @@ export function validateBranchName(raw: unknown, options: BranchNamePolicyOption
 export function branchRef(branch: unknown, options: BranchNamePolicyOptions = {}): string {
   return `refs/heads/${validateBranchName(branch, options)}`;
 }
-
-export function campaignBranchName(input: { readonly title: string; readonly identity: string }): string {
-  return validateBranchName(
-    `campaign/${branchSlugSegment(input.title)}-${input.identity}`,
-    { purpose: 'CAMPAIGN_WORKSPACE_BRANCH' },
-  );
-}

package/src/cli/repositories/controller-home.ts

@@ -1,6 +1,6 @@
-import { existsSync, mkdirSync } from 'fs';
+import { existsSync, lstatSync, mkdirSync, readlinkSync, renameSync, rmSync, symlinkSync } from 'fs';
 import { homedir } from 'os';
-import { join, resolve } from 'path';
+import { basename, dirname, join, relative, resolve } from 'path';
 
 export function resolveControllerHome(explicit?: string): string {
   const configured = explicit?.trim()
@@ -29,8 +29,115 @@ export function resolveRepoPreferredControllerHome(repoRoot?: string, explicit?:
   return resolveControllerHome();
 }
 
+export function repoLocalNoIndexControllerHome(
+  controllerHome: string,
+  platform: NodeJS.Platform = process.platform,
+): string | undefined {
+  const home = resolve(controllerHome);
+  if (platform !== 'darwin' || basename(home) !== 'controller-home' || basename(dirname(home)) !== '_ops') return undefined;
+  return `${home}.noindex`;
+}
+
+export function ensureControllerHomeStorage(
+  controllerHome: string,
+  platform: NodeJS.Platform = process.platform,
+): string {
+  const home = resolve(controllerHome);
+  const physical = repoLocalNoIndexControllerHome(home, platform);
+  if (!physical || existsSync(home)) return home;
+
+  let logicalEntryExists = false;
+  try { logicalEntryExists = lstatSync(home).isSymbolicLink(); } catch { /* absent */ }
+  mkdirSync(physical, { recursive: true });
+  if (!logicalEntryExists) {
+    const target = relative(dirname(home), physical) || basename(physical);
+    try {
+      symlinkSync(target, home, 'dir');
+    } catch (error) {
+      if (!existsSync(home)) throw error;
+    }
+  }
+  return home;
+}
+
+export interface ControllerHomeStorageMigration {
+  migrated: boolean;
+  logicalHome: string;
+  physicalHome?: string;
+}
+
+function symlinkTargetPath(path: string): string {
+  return resolve(dirname(path), readlinkSync(path));
+}
+
+export function repoLocalControllerHomeStorageNeedsMigration(
+  controllerHome: string,
+  platform: NodeJS.Platform = process.platform,
+): boolean {
+  const logicalHome = resolve(controllerHome);
+  const physicalHome = repoLocalNoIndexControllerHome(logicalHome, platform);
+  if (!physicalHome) return false;
+  let stat;
+  try {
+    stat = lstatSync(logicalHome);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+  if (stat.isSymbolicLink()) {
+    if (symlinkTargetPath(logicalHome) !== physicalHome) {
+      throw new Error(`CONTROLLER_HOME_NOINDEX_SYMLINK_CONFLICT: ${logicalHome}`);
+    }
+    if (!existsSync(physicalHome)) {
+      throw new Error(`CONTROLLER_HOME_NOINDEX_TARGET_MISSING: ${physicalHome}`);
+    }
+    return false;
+  }
+  if (!stat.isDirectory()) throw new Error(`CONTROLLER_HOME_STORAGE_UNSUPPORTED: ${logicalHome}`);
+  if (existsSync(physicalHome)) throw new Error(`CONTROLLER_HOME_NOINDEX_TARGET_EXISTS: ${physicalHome}`);
+  return true;
+}
+
+/** Caller must prove the Canonical Runtime is fully stopped before invoking. */
+export function migrateStoppedRepoLocalControllerHomeStorage(
+  controllerHome: string,
+  platform: NodeJS.Platform = process.platform,
+): ControllerHomeStorageMigration {
+  const logicalHome = resolve(controllerHome);
+  const physicalHome = repoLocalNoIndexControllerHome(logicalHome, platform);
+  if (!physicalHome || !repoLocalControllerHomeStorageNeedsMigration(logicalHome, platform)) {
+    return { migrated: false, logicalHome, physicalHome };
+  }
+  renameSync(logicalHome, physicalHome);
+  try {
+    const target = relative(dirname(logicalHome), physicalHome) || basename(physicalHome);
+    symlinkSync(target, logicalHome, 'dir');
+    if (!lstatSync(logicalHome).isSymbolicLink() || symlinkTargetPath(logicalHome) !== physicalHome || !existsSync(physicalHome)) {
+      throw new Error(`CONTROLLER_HOME_NOINDEX_POSTCHECK_FAILED: ${logicalHome}`);
+    }
+    return { migrated: true, logicalHome, physicalHome };
+  } catch (error) {
+    try { rmSync(logicalHome, { force: true }); } catch { /* best effort */ }
+    if (!existsSync(logicalHome) && existsSync(physicalHome)) renameSync(physicalHome, logicalHome);
+    throw error;
+  }
+}
+
+/** Caller must prove the Canonical Runtime is fully stopped before invoking. */
+export function rollbackStoppedRepoLocalControllerHomeStorage(migration: ControllerHomeStorageMigration): void {
+  if (!migration.migrated || !migration.physicalHome) return;
+  const { logicalHome, physicalHome } = migration;
+  const stat = lstatSync(logicalHome);
+  if (!stat.isSymbolicLink() || symlinkTargetPath(logicalHome) !== physicalHome) {
+    throw new Error(`CONTROLLER_HOME_NOINDEX_ROLLBACK_CONFLICT: ${logicalHome}`);
+  }
+  if (!existsSync(physicalHome)) throw new Error(`CONTROLLER_HOME_NOINDEX_ROLLBACK_TARGET_MISSING: ${physicalHome}`);
+  rmSync(logicalHome, { force: true });
+  renameSync(physicalHome, logicalHome);
+}
+
 export function ensureControllerHome(explicit?: string): string {
-  const home = resolveControllerHome(explicit);
+  const home = ensureControllerHomeStorage(resolveControllerHome(explicit));
   for (const child of ['', 'repositories', 'system', 'locks', 'indexes', 'audit', 'mcp', 'sessions', 'work-handles']) {
     mkdirSync(join(home, child), { recursive: true });
   }

package/src/cli/repositories/safe-patch.ts

@@ -415,7 +415,7 @@ export function applySafePatch(repository: RepositoryRecord, input: {
     failures,
     plan,
     next: status === 'applied'
-      ? 'Run repository_git_diff or repository_git_status, then repository_git_commit when ready.'
+      ? 'Review the returned edit-session diff evidence. Run focused validation only after the coherent edit batch is stable, then commit when acceptance evidence is sufficient.'
       : 'Inspect failures[].context, refresh the operation text, and re-run only the failed chunk or remaining operations.',
   };
 }

package/src/cli/repositories/selected-path-actions.ts

@@ -31,13 +31,13 @@ export interface SelectedPathCommitResult {
   error?: { code: string; message: string };
 }
 
-export interface HandoffArtifactPreview {
+export interface TransferArtifactPreview {
   path: string;
   exists: boolean;
   preview?: string;
 }
 
-export interface PreparedHandoffArtifacts {
+export interface PreparedTransferArtifacts {
   reason: string;
   usedScript: boolean;
   fallbackUsed: boolean;
@@ -45,7 +45,7 @@ export interface PreparedHandoffArtifacts {
   exitCode?: number;
   stdout?: string;
   stderr?: string;
-  artifacts: HandoffArtifactPreview[];
+  artifacts: TransferArtifactPreview[];
 }
 
 function boundedOutputBytes(value: number | undefined): number {
@@ -129,7 +129,7 @@ function stagedPaths(repository: RepositoryRecord, paths: string[]): string[] {
     .filter(Boolean);
 }
 
-function artifactPreview(repository: RepositoryRecord, path: string): HandoffArtifactPreview {
+function artifactPreview(repository: RepositoryRecord, path: string): TransferArtifactPreview {
   const absolute = join(repository.canonicalRoot, path);
   if (!existsSync(absolute)) return { path, exists: false };
   const content = redactProcessOutput(readFileSync(absolute, 'utf-8'));
@@ -147,7 +147,7 @@ function repositoryChangedPaths(repository: RepositoryRecord): string[] {
   return [...new Set([tracked, staged, untracked].join('\n').split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean))].sort();
 }
 
-function writePatchHandoffArtifact(repository: RepositoryRecord, handoffDir: string, reason: string): HandoffArtifactPreview {
+function writePatchTransferArtifact(repository: RepositoryRecord, transferDir: string, reason: string): TransferArtifactPreview {
   const diff = runGit(repository, ['diff', '--binary'], 512 * 1024).stdout;
   const stagedDiff = runGit(repository, ['diff', '--cached', '--binary'], 512 * 1024).stdout;
   const touchedPaths = repositoryChangedPaths(repository);
@@ -158,27 +158,29 @@ function writePatchHandoffArtifact(repository: RepositoryRecord, handoffDir: str
     touchedPaths,
     checks: [],
     actor: 'forge',
-    source: `fallback-handoff:${reason}`,
+    source: `patch-transfer:${reason}`,
     notes: [
       'Integration must use selected-path review gates.',
       'Do not overwrite unrelated dirty files; rerun conflict detection before applying this patch.',
     ],
   });
-  const patchPath = join(handoffDir, 'patch.json');
+  const patchPath = join(transferDir, 'patch.json');
   writeFileSync(patchPath, `${JSON.stringify(artifact, null, 2)}\n`, 'utf-8');
-  return artifactPreview(repository, '.ai/harness/handoff/patch.json');
+  return artifactPreview(repository, '.ai/harness/transfers/patch.json');
 }
 
-function ensureFallbackArtifact(repository: RepositoryRecord, reason: string): HandoffArtifactPreview {
-  const handoffDir = join(repository.canonicalRoot, '.ai', 'harness', 'handoff');
-  mkdirSync(handoffDir, { recursive: true });
-  const patchArtifact = writePatchHandoffArtifact(repository, handoffDir, reason);
+function ensureFallbackArtifact(repository: RepositoryRecord, reason: string): TransferArtifactPreview {
+  const transferDir = join(repository.canonicalRoot, '.ai', 'harness', 'transfers');
+  const sessionDir = join(repository.canonicalRoot, '.ai', 'harness', 'session');
+  mkdirSync(transferDir, { recursive: true });
+  mkdirSync(sessionDir, { recursive: true });
+  const patchArtifact = writePatchTransferArtifact(repository, transferDir, reason);
   const timestamp = new Date().toISOString();
-  const currentPath = join(handoffDir, 'current.md');
-  const resumePath = join(handoffDir, 'resume.md');
+  const currentPath = join(sessionDir, 'continuation.md');
+  const resumePath = join(sessionDir, 'resume.md');
   if (!existsSync(currentPath)) {
     writeFileSync(currentPath, [
-      '# Harness Handoff',
+      '# Forge Session Continuation Snapshot',
       '',
       `> **Generated**: ${timestamp}`,
       `> **Reason**: ${reason}`,
@@ -187,7 +189,7 @@ function ensureFallbackArtifact(repository: RepositoryRecord, reason: string): H
       '## Exact Next Step',
       '',
       '- Inspect the selected-path Git diff and continue from this repository state.',
-      '- Review `.ai/harness/handoff/patch.json` before any integration attempt.',
+      '- Review `.ai/harness/transfers/patch.json` before any integration attempt.',
       '',
     ].join('\n'), 'utf-8');
   }
@@ -197,8 +199,8 @@ function ensureFallbackArtifact(repository: RepositoryRecord, reason: string): H
       '',
       `- Repository: \`${repository.canonicalRoot}\``,
       `- Reason: \`${reason}\``,
-      '- Patch artifact: `.ai/harness/handoff/patch.json`',
-      '- Next: open `.ai/harness/handoff/current.md` and continue from the recorded state.',
+      '- Patch artifact: `.ai/harness/transfers/patch.json`',
+      '- Next: open `.ai/harness/session/continuation.md` and continue from the recorded state.',
       '',
     ].join('\n'), 'utf-8');
   }
@@ -290,10 +292,10 @@ export function commitSelectedPaths(
   };
 }
 
-export function prepareFallbackHandoffArtifacts(
+export function prepareTransferArtifacts(
   repository: RepositoryRecord,
   input: { reason?: unknown },
-): PreparedHandoffArtifacts {
+): PreparedTransferArtifacts {
   const reason = String(input.reason ?? 'manual').trim() || 'manual';
   const script = join(repository.canonicalRoot, 'scripts', 'prepare-handoff.sh');
   const usedScript = existsSync(script);
@@ -321,8 +323,8 @@ export function prepareFallbackHandoffArtifacts(
     ok = exitCode === 0 && !result.error;
   }
 
-  const beforeCurrent = existsSync(join(repository.canonicalRoot, '.ai', 'harness', 'handoff', 'current.md'));
-  const beforeResume = existsSync(join(repository.canonicalRoot, '.ai', 'harness', 'handoff', 'resume.md'));
+  const beforeCurrent = existsSync(join(repository.canonicalRoot, '.ai', 'harness', 'session', 'continuation.md'));
+  const beforeResume = existsSync(join(repository.canonicalRoot, '.ai', 'harness', 'session', 'resume.md'));
   const patchArtifact = ensureFallbackArtifact(repository, reason);
   const fallbackUsed = !usedScript || !ok || !beforeCurrent || !beforeResume;
 
@@ -333,8 +335,8 @@ export function prepareFallbackHandoffArtifacts(
     ok: usedScript ? ok : true,
     ...(usedScript ? { exitCode, stdout, stderr } : {}),
     artifacts: [
-      artifactPreview(repository, '.ai/harness/handoff/current.md'),
-      artifactPreview(repository, '.ai/harness/handoff/resume.md'),
+      artifactPreview(repository, '.ai/harness/session/continuation.md'),
+      artifactPreview(repository, '.ai/harness/session/resume.md'),
       patchArtifact,
     ],
   };

package/src/core/adoption/gitignore-plan.ts

@@ -39,7 +39,6 @@ export const GITIGNORE_MANAGED_BLOCK_CONTENT = [
   ".claude/.trace.jsonl",
   ".claude/.session-handoff.md",
   ".claude/.task-state.json",
-  ".claude/.task-handoff.md",
   ".claude/.codegraph-state/",
   ".claude/*.tmp",
   ".claude/*.bak",
@@ -52,8 +51,8 @@ export const GITIGNORE_MANAGED_BLOCK_CONTENT = [
   ".ai/harness/archive/",
   ".ai/harness/backups/",
   ".ai/harness/failures/latest.jsonl",
-  ".ai/harness/handoff/current.md",
-  ".ai/harness/handoff/resume.md",
+  ".ai/harness/session/continuation.md",
+  ".ai/harness/session/resume.md",
   ".ai/harness/capability-context/",
   ".ai/harness/security/*",
   "!.ai/harness/security/.gitkeep",

package/src/core/adoption/plan.ts

@@ -26,7 +26,10 @@ const MINIMAL_DIRS = [
   "tasks/notes",
   "docs",
   ".ai/harness/checks",
-  ".ai/harness/handoff",
+  ".ai/harness/session",
+  ".ai/harness/controller/packets",
+  ".ai/harness/projections",
+  ".ai/harness/transfers",
 ] as const;
 
 const STANDARD_EXTRA_DIRS = [