@moretea-labs/forge 1.8.0 → 1.8.1

package/src/cli/repositories/command-scope.ts

@@ -33,11 +33,34 @@ function nearestExistingPath(candidate: string): string | undefined {
   return current;
 }
 
+/**
+ * Minimal command execution target. Repository identity stays optional: an
+ * arbitrary workspace target carries only its scope key and root, so command
+ * policy/audit/cwd checks need no fabricated repository record.
+ */
+export interface RepositoryCommandScopeTarget {
+  canonicalRoot: string;
+  /** Registered repository id (`RepositoryRecord.repoId`); absent for an arbitrary workspace target. */
+  repoId?: string;
+  /** Workspace scope key; present only when the target is not a repository. */
+  workspaceScopeKey?: string;
+  activeCheckoutId?: string;
+  defaultBranch?: string;
+  enabled?: boolean;
+}
+
+/** Canonical scope key for command policy/audit/approval storage. */
+export function commandExecutionScopeKey(target: RepositoryCommandScopeTarget): string {
+  const key = target.repoId?.trim() || target.workspaceScopeKey?.trim();
+  if (!key) throw new Error('COMMAND_TARGET_SCOPE_REQUIRED: command target requires a repository id or workspace scope key');
+  return key;
+}
+
 export function resolveRepositoryCommandCwd(
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   requestedCwd: string | undefined,
 ): { root: string; cwd: string; relativeCwd: string } {
-  if (!repository.enabled) throw new Error(`REPOSITORY_DISABLED: ${repository.repoId}`);
+  if (repository.enabled === false) throw new Error(`REPOSITORY_DISABLED: ${commandExecutionScopeKey(repository)}`);
   const root = realpathSync(repository.canonicalRoot);
   const raw = requestedCwd?.trim() || '.';
   if (raw.includes('\0')) throw new Error('COMMAND_SCOPE_DENIED: cwd contains a null byte');
@@ -258,7 +281,7 @@ interface RepositoryCommandPathPolicyOptions {
 }
 
 interface SourceControllerRoundCompatibilityScope {
-  operation: 'round-continue' | 'round-close';
+  operation: 'round-close';
   controllerHome: string;
   workId: string;
   controllerAuthorityId: string;
@@ -274,11 +297,9 @@ function sourceControllerRoundCompatibilityScope(
   const args = command.args ?? [];
   if (executable !== 'bun' || args[0] !== 'src/cli/index.ts' || args[1] !== 'chatgpt') return undefined;
   const operation = args[2];
-  if (operation !== 'round-continue' && operation !== 'round-close') return undefined;
+  if (operation !== 'round-close') return undefined;
 
-  const allowedFlags = operation === 'round-continue'
-    ? new Set(['--controller-home', '--repo-id', '--work-id', '--controller-authority-id', '--relay-scope-id', '--reason', '--timeout-ms'])
-    : new Set(['--controller-home', '--repo-id', '--work-id', '--controller-authority-id', '--relay-scope-id', '--disposition', '--handoff-id', '--reason']);
+  const allowedFlags = new Set(['--controller-home', '--repo-id', '--work-id', '--controller-authority-id', '--relay-scope-id', '--disposition', '--handoff-id', '--reason']);
   const values = new Map<string, string>();
   for (let index = 3; index < args.length; index += 2) {
     const flag = args[index];
@@ -300,14 +321,12 @@ function sourceControllerRoundCompatibilityScope(
   if (requestedControllerHome !== configuredControllerHome) {
     throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_CONTROLLER_HOME_MISMATCH:${requestedControllerHome}`);
   }
-  if (operation === 'round-close') {
-    const disposition = values.get('--disposition');
-    if (!disposition || !['wait', 'wait_for_user', 'goal_complete'].includes(disposition)) {
-      throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_DISPOSITION_INVALID:${disposition ?? 'missing'}`);
-    }
-    if (disposition === 'wait_for_user' && !values.get('--handoff-id')?.trim()) {
-      throw new Error('SOURCE_CONTROLLER_ROUND_COMMAND_HANDOFF_REQUIRED');
-    }
+  const disposition = values.get('--disposition');
+  if (!disposition || !['wait', 'wait_for_user', 'goal_complete'].includes(disposition)) {
+    throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_DISPOSITION_INVALID:${disposition ?? 'missing'}`);
+  }
+  if (disposition === 'wait_for_user' && !values.get('--handoff-id')?.trim()) {
+    throw new Error('SOURCE_CONTROLLER_ROUND_COMMAND_HANDOFF_REQUIRED');
   }
   return {
     operation,
@@ -328,7 +347,7 @@ function grantCoversPath(grant: ExternalFilesystemGrant, canonicalPath: string,
 }
 
 function operationForToken(words: string[], index: number, external: string, cwd: string, root: string): RepositoryCommandExternalPathOperation | 'external_write' | 'unsupported' {
-  const program = words[0]?.toLowerCase();
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
   if (!program) return 'unsupported';
   if (program === 'cp' || program === 'install') {
     const operands = words.slice(1).filter((word) => word && !word.startsWith('-'));

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

@@ -253,7 +253,10 @@ export function ensureRepoPreferredControllerHome(repoRoot?: string, explicit?:
   return ensureControllerHome(resolveRepoPreferredControllerHome(repoRoot, explicit));
 }
 
+/** Legacy adapter-only sentinel. Never use this as a canonical storage or resource scope. */
 export const CONTROLLER_SCOPE_REPO_ID = '__controller__';
+/** Canonical mechanical scope for state owned by the serving ForgeInstance itself. */
+export const FORGE_INSTANCE_SCOPE_KEY = 'forge-instance';
 
 /** Human-editable user Workflow Asset content. Machine workflow state stays in control-plane persistence. */
 export function controllerWorkflowContentRoot(controllerHome: string): string {
@@ -283,6 +286,51 @@ export function repositoryControllerRoot(controllerHome: string, repoId: string)
     : join(resolveControllerHome(durableHome), 'repositories', repoId);
 }
 
+/** Reserved prefix for arbitrary workspace scopes; registered repository ids are `repo_*`. */
+export const WORKSPACE_SCOPE_PREFIX = 'workspace_';
+
+/**
+ * Reserved scope key for portable semantic facts (Requirement/Plan/Work) that
+ * belong to the ForgeInstance rather than to one repository. Repository and
+ * project placement stays optional provenance on those records.
+ */
+export const SEMANTIC_SCOPE_KEY = 'semantic';
+
+export function isWorkspaceScopeKey(scopeKey: string): boolean {
+  return scopeKey.trim().startsWith(WORKSPACE_SCOPE_PREFIX);
+}
+
+export function isSemanticScopeKey(scopeKey: string): boolean {
+  return scopeKey.trim() === SEMANTIC_SCOPE_KEY;
+}
+
+/**
+ * Controller-Home root for an arbitrary workspace scope. A workspace has no
+ * repository semantics, so its operation facts own a sibling partition instead
+ * of a repository partition.
+ */
+export function workspaceScopeRoot(controllerHome: string, scopeKey: string): string {
+  const key = scopeKey.trim();
+  if (!isWorkspaceScopeKey(key)) throw new Error(`WORKSPACE_SCOPE_KEY_REQUIRED: ${scopeKey}`);
+  return join(resolveControllerHome(durableControllerHome(controllerHome)), 'workspaces', key);
+}
+
+/**
+ * Controller-Home root for one operation scope key. Repository scopes (including
+ * the controller-system sentinel) keep their established root; workspace scopes
+ * own the workspace partition.
+ */
+export function scopedOperationRoot(controllerHome: string, scopeKey: string): string {
+  const key = scopeKey.trim();
+  return key === FORGE_INSTANCE_SCOPE_KEY
+    ? controllerSystemRoot(controllerHome)
+    : isWorkspaceScopeKey(key)
+      ? workspaceScopeRoot(controllerHome, key)
+      : isSemanticScopeKey(key)
+        ? join(resolveControllerHome(durableControllerHome(controllerHome)), SEMANTIC_SCOPE_KEY)
+        : repositoryControllerRoot(controllerHome, key);
+}
+
 export function ensureRepositoryControllerLayout(controllerHome: string, repoId: string): string {
   const root = repositoryControllerRoot(controllerHome, repoId);
   for (const child of [

package/src/cli/repositories/ephemeral-workspace.ts

@@ -1,7 +1,7 @@
 import { createHash } from 'crypto';
 import { existsSync, realpathSync, statSync } from 'fs';
-import { isAbsolute, join } from 'path';
-import type { RepositoryRecord } from './types';
+import { isAbsolute } from 'path';
+import type { RepositoryCommandScopeTarget } from './command-scope';
 
 export interface EphemeralWorkspaceCoordinates {
   workspaceId: string;
@@ -10,7 +10,11 @@ export interface EphemeralWorkspaceCoordinates {
 }
 
 export interface EphemeralWorkspaceTarget extends EphemeralWorkspaceCoordinates {
-  repository: RepositoryRecord;
+  /**
+   * Typed command target for an arbitrary workspace: it carries the workspace
+   * scope key and root, and no repository identity at all.
+   */
+  commandTarget: RepositoryCommandScopeTarget;
 }
 
 export function ephemeralWorkspaceCoordinates(rootInput: string): EphemeralWorkspaceCoordinates {
@@ -29,34 +33,20 @@ export function ephemeralWorkspaceCoordinates(rootInput: string): EphemeralWorks
   };
 }
 
-export function resolveEphemeralWorkspaceTarget(rootInput: string, controllerHome: string): EphemeralWorkspaceTarget {
+/**
+ * `controllerHome` is retained for call-site compatibility; an arbitrary
+ * workspace owns no controller-scoped repository record.
+ */
+export function resolveEphemeralWorkspaceTarget(rootInput: string, _controllerHome?: string): EphemeralWorkspaceTarget {
   const coordinates = ephemeralWorkspaceCoordinates(rootInput);
-  const now = new Date().toISOString();
-  const repository: RepositoryRecord = {
-    schemaVersion: 1,
-    repoId: coordinates.workspaceId,
-    displayName: `Ephemeral Workspace (${coordinates.canonicalRoot.split(/[\\/]/).at(-1) || 'root'})`,
-    localRoot: coordinates.canonicalRoot,
-    canonicalRoot: coordinates.canonicalRoot,
-    activeCheckoutId: coordinates.checkoutId,
-    checkouts: [{
-      checkoutId: coordinates.checkoutId,
-      localRoot: coordinates.canonicalRoot,
+  return {
+    ...coordinates,
+    commandTarget: {
       canonicalRoot: coordinates.canonicalRoot,
-      worktree: false,
-      branch: null,
-      createdAt: now,
-      updatedAt: now,
-      lastSeenAt: now,
-      lifecycle: 'active',
-    }],
-    repositoryType: 'unknown',
-    enabled: true,
-    createdAt: now,
-    updatedAt: now,
-    lastSeenAt: now,
-    configurationPath: join(controllerHome, 'ephemeral-workspaces', `${coordinates.workspaceId}.json`),
-    stateStorageStrategy: 'controller-home',
+      workspaceScopeKey: coordinates.workspaceId,
+      // The workspace's own checkout coordinate, never a repository checkout id.
+      activeCheckoutId: coordinates.checkoutId,
+      enabled: true,
+    },
   };
-  return { ...coordinates, repository };
 }

package/src/cli/repositories/git-command-executor.ts

@@ -3,7 +3,7 @@ import { spawnSync } from 'child_process';
 import { appendFileSync, mkdirSync, realpathSync } from 'fs';
 import { dirname, join, relative } from 'path';
 import { capProcessOutput, redactProcessOutput } from '../../effects/process-runner';
-import { repositoryControllerRoot } from './controller-home';
+import { scopedOperationRoot } from './controller-home';
 import { classifyRepositoryCommand, type RepositoryCommandAuthorization, type RepositoryCommandClassification } from './command-classifier';
 import { resolveRepositoryCommandCwd } from './command-scope';
 import type { RepositoryRecord } from './types';
@@ -209,7 +209,7 @@ function snapshotChanged(before: RepositoryGitSnapshot, after: RepositoryGitSnap
 }
 
 function auditExecution(controllerHome: string, repository: RepositoryRecord, execution: RepositoryGitExecution): void {
-  const path = join(repositoryControllerRoot(controllerHome, repository.repoId), 'audit', 'git-commands.jsonl');
+  const path = join(scopedOperationRoot(controllerHome, repository.repoId), 'audit', 'git-commands.jsonl');
   mkdirSync(dirname(path), { recursive: true });
   appendFileSync(path, `${JSON.stringify({
     timestamp: new Date().toISOString(),

package/src/cli/repositories/registry.ts

@@ -6,6 +6,7 @@ import {
   realpathSync,
   renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'fs';
 import { dirname, join, relative, resolve } from 'path';
@@ -291,6 +292,51 @@ function readRegistryFile(path: string, strict: boolean): RepositoryRegistry | u
   }
 }
 
+interface RepositoryRegistryReadSnapshot {
+  fileIdentity: string;
+  registry: RepositoryRegistry;
+}
+
+const repositoryRegistryReadSnapshots = new Map<string, RepositoryRegistryReadSnapshot>();
+
+function registryFileIdentity(path: string): string | undefined {
+  try {
+    const stat = statSync(path, { bigint: true });
+    return `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+  } catch {
+    return undefined;
+  }
+}
+
+function cloneRepositoryRecord(record: RepositoryRecord): RepositoryRecord {
+  return {
+    ...record,
+    checkouts: record.checkouts.map((checkout) => ({ ...checkout })),
+    github: record.github
+      ? { ...record.github, labels: record.github.labels ? [...record.github.labels] : undefined }
+      : undefined,
+  };
+}
+
+function loadRepositoryRegistryReadSnapshot(controllerHome?: string): RepositoryRegistry {
+  const path = registryPath(controllerHome);
+  const beforeIdentity = registryFileIdentity(path);
+  const cached = beforeIdentity ? repositoryRegistryReadSnapshots.get(path) : undefined;
+  if (cached && cached.fileIdentity === beforeIdentity) return cached.registry;
+
+  let registry = readRegistryFile(path, true) ?? defaultRegistry();
+  let afterIdentity = registryFileIdentity(path);
+  if (beforeIdentity && afterIdentity && beforeIdentity !== afterIdentity) {
+    // A cross-process atomic replacement raced this read. Re-read once from the
+    // new physical authority instead of caching a mixed-generation snapshot.
+    registry = readRegistryFile(path, true) ?? defaultRegistry();
+    afterIdentity = registryFileIdentity(path);
+  }
+  if (afterIdentity) repositoryRegistryReadSnapshots.set(path, { fileIdentity: afterIdentity, registry });
+  else repositoryRegistryReadSnapshots.delete(path);
+  return registry;
+}
+
 function timestampValue(value: string | undefined): number {
   const parsed = value ? Date.parse(value) : Number.NaN;
   return Number.isFinite(parsed) ? parsed : 0;
@@ -555,17 +601,18 @@ export function repositorySummary(record: RepositoryRecord): RepositorySummary {
 }
 
 export function listRepositories(controllerHome?: string, options: { includeRemoved?: boolean } = {}): RepositoryRecord[] {
-  return loadRepositoryRegistry(controllerHome).repositories
+  return loadRepositoryRegistryReadSnapshot(controllerHome).repositories
     .filter((record) => options.includeRemoved === true || !record.removedAt)
-    .sort((a, b) => a.displayName.localeCompare(b.displayName) || a.repoId.localeCompare(b.repoId));
+    .sort((a, b) => a.displayName.localeCompare(b.displayName) || a.repoId.localeCompare(b.repoId))
+    .map(cloneRepositoryRecord);
 }
 
 export function getRepository(repoId: string, controllerHome?: string, options: { includeRemoved?: boolean } = {}): RepositoryRecord {
-  const record = loadRepositoryRegistry(controllerHome).repositories.find((candidate) => candidate.repoId === repoId);
+  const record = loadRepositoryRegistryReadSnapshot(controllerHome).repositories.find((candidate) => candidate.repoId === repoId);
   if (!record || (record.removedAt && options.includeRemoved !== true)) {
     throw new Error(`repository not found: ${repoId}`);
   }
-  return record;
+  return cloneRepositoryRecord(record);
 }
 
 export type RepositoryCheckoutSelectionErrorCode = 'CHECKOUT_NOT_FOUND' | 'CHECKOUT_NOT_ACTIVE';
@@ -635,13 +682,29 @@ export function registerRepository(input: RegisterRepositoryInput): RepositoryRe
     ? repositoryByGitCommonDirectory(registry.repositories, canonicalRoot)
     : undefined;
   const existingIdentity = existingByRoot ?? existingByCommonDirectory;
-  const derivedRepoId = input.repoIdOverride?.trim()
+  const explicitRepoId = input.repoIdOverride?.trim();
+  const derivedRepoId = explicitRepoId
     || existingIdentity?.repoId
     || localIdentity.repoId
     || (canonicalRemote ? stableRemoteRepoId(canonicalRemote) : newLocalRepoId());
-  const repoId = existingIdentity?.repoId ?? derivedRepoId;
+  const existingByDerivedId = registry.repositories.find((record) => record.repoId === derivedRepoId);
+  // Repository identity is rooted in one Git checkout family, not merely one
+  // remote URL. Two independent clones of the same remote have different Git
+  // common directories and must remain separate Repository records. The one
+  // intentional exception is an explicit registration replacement; legacy
+  // repo-local identity may also restore a record whose old canonical root no
+  // longer exists after a filesystem move.
+  const explicitReplacement = Boolean(explicitRepoId && existingByDerivedId);
+  const legacyMovedRoot = Boolean(
+    !explicitRepoId
+    && localIdentity.repoId
+    && existingByDerivedId
+    && !existsSync(existingByDerivedId.canonicalRoot),
+  );
+  const existing = existingIdentity ?? (explicitReplacement || legacyMovedRoot ? existingByDerivedId : undefined);
+  const repoId = existing?.repoId
+    ?? (existingByDerivedId && !existingIdentity ? newLocalRepoId() : derivedRepoId);
   const checkoutId = stableCheckoutId(repoId, canonicalRoot);
-  const existing = existingIdentity ?? registry.repositories.find((record) => record.repoId === repoId);
   const checkout: RepositoryCheckout = {
     checkoutId,
     localRoot: canonicalRoot,
@@ -659,8 +722,8 @@ export function registerRepository(input: RegisterRepositoryInput): RepositoryRe
   // A repository-scoped command may start from a managed checkout (for example
   // immutable release construction). Registering that path must add/update the
   // checkout only; it must never promote the ephemeral worktree to repository
-  // canonical authority. Explicit activation remains available through
-  // addRepositoryCheckout({ activate: true }).
+  // canonical authority. Active checkout selection is separate authority held
+  // by activeCheckoutId; canonicalRoot remains the repository registration root.
   if (existing && worktree && existing.canonicalRemote && canonicalRemote !== existing.canonicalRemote) {
     throw new Error(`CHECKOUT_REPOSITORY_MISMATCH: ${canonicalRoot}`);
   }
@@ -776,6 +839,9 @@ export function addRepositoryCheckout(input: AddRepositoryCheckoutInput): Reposi
   if (current.canonicalRemote && canonicalRemote !== current.canonicalRemote) {
     throw new Error(`CHECKOUT_REPOSITORY_MISMATCH: ${canonicalRoot}`);
   }
+  if (!repositoryCheckoutRootMatches(current, canonicalRoot)) {
+    throw new Error(`CHECKOUT_REPOSITORY_MISMATCH: ${canonicalRoot}`);
+  }
   const timestamp = now();
   const checkoutId = stableCheckoutId(current.repoId, canonicalRoot);
   const checkout: RepositoryCheckout = {
@@ -792,14 +858,14 @@ export function addRepositoryCheckout(input: AddRepositoryCheckoutInput): Reposi
   const activate = input.activate === true;
   const next: RepositoryRecord = {
     ...current,
-    ...(activate ? { localRoot: canonicalRoot, canonicalRoot, activeCheckoutId: checkoutId } : {}),
+    ...(activate ? { activeCheckoutId: checkoutId } : {}),
     checkouts: [...current.checkouts.filter((value) => value.checkoutId !== checkoutId), checkout],
     updatedAt: timestamp,
     lastSeenAt: timestamp,
   };
   registry.repositories[index] = next;
   saveRepositoryRegistry(registry, home);
-  return next;
+  return activate ? selectRepositoryCheckout(next, checkoutId) : next;
 }
 
 export function setRepositoryCheckoutLifecycle(input: SetRepositoryCheckoutLifecycleInput): RepositoryRecord {

package/src/cli/repositories/structured-git.ts

@@ -98,6 +98,16 @@ function gitText(repository: RepositoryRecord, args: string[]): string | null {
   return result.ok && result.stdout.trim() ? result.stdout.trim() : null;
 }
 
+function stashSelectorForOid(repository: RepositoryRecord, oid: string): string | null {
+  const result = runGit(repository, ['stash', 'list', '--format=%H%x00%gd'], 64 * 1024);
+  if (!result.ok) return null;
+  for (const line of result.stdout.split(/\r?\n/)) {
+    const [candidateOid, selector] = line.split('\0');
+    if (candidateOid === oid && selector) return selector;
+  }
+  return null;
+}
+
 function assertSafeBranchName(raw: unknown): string {
   try {
     return validateBranchName(raw, { purpose: 'GIT_BRANCH' });
@@ -414,6 +424,7 @@ export function repositoryGitFinishWorkflow(controllerHome: string, repository:
   const requestedPreservedDirtyPaths = normalizePaths(input.preserveDirtyTargetPaths);
   const currentDirtyPaths = [...new Set([...before.staged, ...before.unstaged, ...before.untracked])].sort();
   const preserveDirtyTargetInPlace = alreadyOnTarget && requestedPreservedDirtyPaths.length > 0;
+  let equivalentOverlappingDirtyPaths: string[] = [];
   if (preserveDirtyTargetInPlace) {
     const requested = new Set(requestedPreservedDirtyPaths);
     if (requested.size !== currentDirtyPaths.length || currentDirtyPaths.some((path) => !requested.has(path))) {
@@ -426,7 +437,19 @@ export function repositoryGitFinishWorkflow(controllerHome: string, repository:
     const candidatePaths = new Set(candidateDiff.stdout.split(/\r?\n/).map((path) => path.trim()).filter(Boolean));
     const overlapping = currentDirtyPaths.filter((path) => candidatePaths.has(path));
     if (overlapping.length > 0) {
-      return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: before, completed: false, error: { code: 'GIT_DIRTY_TARGET_PATH_CONFLICT', message: `Work-owned dirty target path(s) overlap the integration candidate: ${overlapping.join(', ')}` } };
+      const staged = new Set(before.staged);
+      const unstaged = new Set(before.unstaged);
+      const untracked = new Set(before.untracked);
+      const equivalent = overlapping.every((path) => {
+        if (untracked.has(path) || (!staged.has(path) && !unstaged.has(path))) return false;
+        if (staged.has(path) && !runGit(repository, ['diff', '--cached', '--quiet', featureBranch, '--', path], 8 * 1024).ok) return false;
+        if (unstaged.has(path) && !runGit(repository, ['diff', '--quiet', featureBranch, '--', path], 8 * 1024).ok) return false;
+        return true;
+      });
+      if (!equivalent) {
+        return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: before, completed: false, error: { code: 'GIT_DIRTY_TARGET_PATH_CONFLICT', message: `Work-owned dirty target path(s) overlap the integration candidate: ${overlapping.join(', ')}` } };
+      }
+      equivalentOverlappingDirtyPaths = overlapping;
     }
   }
   if (!before.clean && !alreadyOnTarget) {
@@ -442,6 +465,30 @@ export function repositoryGitFinishWorkflow(controllerHome: string, repository:
   }
   const protectTrackedChanges = alreadyOnTarget && !preserveDirtyTargetInPlace && (before.staged.length > 0 || before.unstaged.length > 0);
   const finishAuthorization = 'explicit_user_request' as const;
+  let equivalentOverlapStashRef: string | null = null;
+  if (equivalentOverlappingDirtyPaths.length > 0) {
+    const stash = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'push', '-m', `forge-finish-equivalent:${input.workId ?? featureBranch}`, '--', ...equivalentOverlappingDirtyPaths], authorization: finishAuthorization, ...input });
+    steps.push({ name: 'stash_equivalent_target_overlap', execution: stash });
+    if (stash.status !== 'executed' || stash.ok !== true) {
+      return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_EQUIVALENT_TARGET_STASH_FAILED', message: stash.stderr || 'Unable to preserve candidate-equivalent dirty target paths before integration.' } };
+    }
+    equivalentOverlapStashRef = gitText(repository, ['rev-parse', 'refs/stash']);
+    if (!equivalentOverlapStashRef) {
+      return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_EQUIVALENT_TARGET_STASH_REFERENCE_MISSING', message: 'Candidate-equivalent target paths were stashed but the recovery stash reference could not be resolved.' } };
+    }
+  }
+  const restoreEquivalentOverlap = (name: string): RepositoryGitExecution | undefined => {
+    if (!equivalentOverlapStashRef) return undefined;
+    const execution = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'apply', '--index', equivalentOverlapStashRef], authorization: finishAuthorization, ...input });
+    steps.push({ name, execution });
+    return execution;
+  };
+  const dropEquivalentOverlapStash = (): void => {
+    if (!equivalentOverlapStashRef) return;
+    const selector = stashSelectorForOid(repository, equivalentOverlapStashRef) ?? equivalentOverlapStashRef;
+    const execution = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'drop', selector], authorization: finishAuthorization, ...input });
+    steps.push({ name: 'drop_equivalent_target_stash', execution });
+  };
   let stashRef: string | null = null;
   if (protectTrackedChanges) {
     const stash = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'push', '-m', `forge-finish:${input.workId ?? featureBranch}`], authorization: finishAuthorization, ...input });
@@ -468,17 +515,30 @@ export function repositoryGitFinishWorkflow(controllerHome: string, repository:
   };
   const dropTrackedStash = (): void => {
     if (!stashRef) return;
-    const execution = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'drop', stashRef], authorization: finishAuthorization, ...input });
+    const selector = stashSelectorForOid(repository, stashRef) ?? stashRef;
+    const execution = executeRepositoryGitCommand(controllerHome, repository, { args: ['stash', 'drop', selector], authorization: finishAuthorization, ...input });
     steps.push({ name: 'drop_target_stash', execution });
   };
   const merge = executeRepositoryGitCommand(controllerHome, repository, { args: ['merge', ...(input.noFf === true ? ['--no-ff'] : ['--ff-only']), featureBranch], authorization: finishAuthorization, ...input });
   steps.push({ name: 'merge_feature', execution: merge });
   if (merge.status !== 'executed' || merge.ok !== true) {
+    const restoreEquivalent = restoreEquivalentOverlap('restore_equivalent_target_overlap_after_merge_failure');
+    if (restoreEquivalent && (restoreEquivalent.status !== 'executed' || restoreEquivalent.ok !== true)) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_EQUIVALENT_TARGET_RESTORE_FAILED', message: restoreEquivalent.stderr || 'Candidate-equivalent target paths could not be restored after merge failure; recovery stash was retained.' } };
+    dropEquivalentOverlapStash();
     const restore = applyTrackedStash('restore_target_changes_after_merge_failure');
     if (restore && (restore.status !== 'executed' || restore.ok !== true)) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_LOCAL_CHANGES_RESTORE_FAILED', message: restore.stderr || 'git stash apply failed while restoring the pre-merge target state' } };
     dropTrackedStash();
     return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_MERGE_FAILED', message: merge.stderr || 'git merge failed' } };
   }
+  if (equivalentOverlappingDirtyPaths.length > 0) {
+    const afterMerge = repositoryGitStatus(repository);
+    const remainingDirty = new Set([...afterMerge.staged, ...afterMerge.unstaged, ...afterMerge.untracked]);
+    const contentMatchesCandidate = runGit(repository, ['diff', '--quiet', featureBranch, '--', ...equivalentOverlappingDirtyPaths], 32 * 1024).ok;
+    if (!contentMatchesCandidate || equivalentOverlappingDirtyPaths.some((path) => remainingDirty.has(path))) {
+      return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: afterMerge, completed: false, error: { code: 'GIT_EQUIVALENT_TARGET_POSTCONDITION_FAILED', message: 'Integrated target did not retain the exact candidate content for a reconciled dirty overlap; recovery stash was retained.' } };
+    }
+    dropEquivalentOverlapStash();
+  }
   const reapply = applyTrackedStash('reapply_target_changes');
   if (reapply && (reapply.status !== 'executed' || reapply.ok !== true)) return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, featureBranch, targetBranch, before, steps, after: repositoryGitStatus(repository), completed: false, error: { code: 'GIT_LOCAL_CHANGES_RESTORE_FAILED', message: reapply.stderr || 'Tracked target changes passed merge-tree preflight but could not be reapplied after merge; recovery stash was retained.' } };
   dropTrackedStash();