@moretea-labs/forge 1.7.2 → 1.8.1

package/src/cli/repositories/repository-snapshot.ts

@@ -5,7 +5,11 @@ import { spawn, spawnSync } from 'child_process';
 import { capProcessOutput, redactProcessOutput } from '../../effects/process-runner';
 import { commandEnvironment, collectOutput } from './command-process';
 
+export type RepositoryCommandMutationEvidence = 'observed' | 'readonly_unobserved' | 'not_applicable';
+
 export interface RepositoryCommandSnapshot {
+  /** Whether this value contains authoritative mutation evidence for comparison. */
+  mutationEvidence: RepositoryCommandMutationEvidence;
   head: string | null;
   branch: string | null;
   status: string;
@@ -15,8 +19,17 @@ export interface RepositoryCommandSnapshot {
   pathFingerprints: Record<string, string>;
 }
 
+function neutralSnapshot(mutationEvidence: Exclude<RepositoryCommandMutationEvidence, 'observed'>): RepositoryCommandSnapshot {
+  return { mutationEvidence, head: null, branch: null, status: '', dirty: false, refsHash: createHash('sha256').update('').digest('hex'), paths: [], pathFingerprints: {} };
+}
+
 export function emptyWorkspaceSnapshot(): RepositoryCommandSnapshot {
-  return { head: null, branch: null, status: '', dirty: false, refsHash: createHash('sha256').update('').digest('hex'), paths: [], pathFingerprints: {} };
+  return neutralSnapshot('not_applicable');
+}
+
+/** Proven-readonly execution deliberately owns no before/after mutation observation. */
+export function readonlyUnobservedRepositorySnapshot(): RepositoryCommandSnapshot {
+  return neutralSnapshot('readonly_unobserved');
 }
 
 function commandOutput(command: string, args: string[], cwd: string, maxOutputBytes: number): { ok: boolean; stdout: string } {
@@ -54,7 +67,7 @@ function buildSnapshot(root: string, head: string | null, branch: string | null,
     byPath.set(path, [...(byPath.get(path) ?? []), line]);
   }
   const paths = [...byPath.keys()].sort();
-  return { head, branch, status, dirty: paths.length > 0, refsHash: createHash('sha256').update(refs).digest('hex'), paths, pathFingerprints: Object.fromEntries(paths.map((path) => [path, pathFingerprint(root, path, byPath.get(path) ?? [])])) };
+  return { mutationEvidence: 'observed', head, branch, status, dirty: paths.length > 0, refsHash: createHash('sha256').update(refs).digest('hex'), paths, pathFingerprints: Object.fromEntries(paths.map((path) => [path, pathFingerprint(root, path, byPath.get(path) ?? [])])) };
 }
 
 export function repositorySnapshot(root: string): RepositoryCommandSnapshot {
@@ -84,7 +97,7 @@ const MAX_DIRTY_PATHS = 200;
 export async function repositorySnapshotAsync(
   root: string,
   signal?: AbortSignal,
-  options: { pathFingerprints?: boolean; fingerprintTimeoutMs?: number } = {},
+  options: { pathFingerprints?: boolean; fingerprintTimeoutMs?: number; fingerprintPaths?: readonly string[] } = {},
 ): Promise<RepositoryCommandSnapshot> {
   const [headResult, branchResult, statusResult, refsResult] = await Promise.all([
     gitAsync(root, ['rev-parse', '--verify', 'HEAD'], signal), gitAsync(root, ['branch', '--show-current'], signal),
@@ -100,25 +113,58 @@ export async function repositorySnapshotAsync(
   if (signal?.aborted) throw new Error('CANCELLED: repository snapshot aborted');
   const lines = statusResult.stdout.split(/\r?\n/).filter((line) => line && !line.startsWith('##'));
   const includePathFingerprints = options.pathFingerprints !== false;
-  if (includePathFingerprints && lines.length > MAX_DIRTY_PATHS) throw new Error(`SNAPSHOT_TOO_DIRTY: ${lines.length} dirty paths exceeds Fast Path cap ${MAX_DIRTY_PATHS}`);
   const byPath = new Map<string, string[]>();
   for (const line of lines) { const path = statusPath(line); if (path) byPath.set(path, [...(byPath.get(path) ?? []), line]); }
   const paths = [...byPath.keys()].sort();
+  const requestedFingerprintPaths = options.fingerprintPaths
+    ? [...new Set(options.fingerprintPaths.map((path) => path.trim().replace(/\\/g, '/').replace(/^\.\//, '')).filter(Boolean))]
+      .filter((path) => byPath.has(path))
+      .sort()
+    : undefined;
+  const fingerprintPaths = requestedFingerprintPaths ?? paths;
+  if (includePathFingerprints && fingerprintPaths.length > MAX_DIRTY_PATHS) {
+    throw new Error(`SNAPSHOT_TOO_DIRTY: ${fingerprintPaths.length} fingerprint paths exceeds Fast Path cap ${MAX_DIRTY_PATHS}`);
+  }
   let pathFingerprints: Record<string, string> = {};
   if (includePathFingerprints) {
     const { computePathFingerprintsAsync } = await import('../../runtime/execution/thin-harness/fingerprint-worker');
     const fingerprintTimeoutMs = typeof options.fingerprintTimeoutMs === 'number' && Number.isFinite(options.fingerprintTimeoutMs)
       ? Math.max(1, Math.trunc(options.fingerprintTimeoutMs))
       : 5_000;
-    const fingerprint = await computePathFingerprintsAsync({ root, paths, statusByPath: Object.fromEntries(byPath), maxFileBytes: 256 * 1024, maxTotalBytes: 8 * 1024 * 1024, maxPaths: MAX_DIRTY_PATHS }, { signal, timeoutMs: fingerprintTimeoutMs });
+    const fingerprintStatusByPath = Object.fromEntries(fingerprintPaths.map((path) => [path, byPath.get(path) ?? []]));
+    const fingerprint = await computePathFingerprintsAsync({ root, paths: fingerprintPaths, statusByPath: fingerprintStatusByPath, maxFileBytes: 256 * 1024, maxTotalBytes: 8 * 1024 * 1024, maxPaths: MAX_DIRTY_PATHS }, { signal, timeoutMs: fingerprintTimeoutMs });
     pathFingerprints = fingerprint.pathFingerprints;
   }
-  return { head, branch: branchResult.ok ? branchResult.stdout || null : null, status: statusResult.stdout, dirty: paths.length > 0, refsHash: createHash('sha256').update(refs).digest('hex'), paths, pathFingerprints };
+  return { mutationEvidence: 'observed', head, branch: branchResult.ok ? branchResult.stdout || null : null, status: statusResult.stdout, dirty: paths.length > 0, refsHash: createHash('sha256').update(refs).digest('hex'), paths, pathFingerprints };
+}
+
+function assertMutationEvidenceComparable(before: RepositoryCommandSnapshot, after: RepositoryCommandSnapshot): void {
+  if (before.mutationEvidence === 'readonly_unobserved' || after.mutationEvidence === 'readonly_unobserved') {
+    throw new Error('SNAPSHOT_COMPARISON_UNOBSERVED: readonly execution has no mutation snapshot to compare');
+  }
+}
+
+function snapshotStatusByPath(snapshot: RepositoryCommandSnapshot): Map<string, string[]> {
+  const byPath = new Map<string, string[]>();
+  for (const line of snapshot.status.split(/\r?\n/).filter((value) => value && !value.startsWith('##'))) {
+    const path = statusPath(line);
+    if (path) byPath.set(path, [...(byPath.get(path) ?? []), line]);
+  }
+  return byPath;
 }
 
 export function changedSnapshotPaths(before: RepositoryCommandSnapshot, after: RepositoryCommandSnapshot): string[] {
-  return [...new Set([...before.paths, ...after.paths])].filter((path) => before.pathFingerprints[path] !== after.pathFingerprints[path]).sort();
+  assertMutationEvidenceComparable(before, after);
+  const beforeStatus = snapshotStatusByPath(before);
+  const afterStatus = snapshotStatusByPath(after);
+  return [...new Set([...before.paths, ...after.paths])].filter((path) => {
+    if ((beforeStatus.get(path) ?? []).join('\n') !== (afterStatus.get(path) ?? []).join('\n')) return true;
+    const beforeFingerprint = before.pathFingerprints[path];
+    const afterFingerprint = after.pathFingerprints[path];
+    return beforeFingerprint !== undefined && afterFingerprint !== undefined && beforeFingerprint !== afterFingerprint;
+  }).sort();
 }
 export function snapshotChanged(before: RepositoryCommandSnapshot, after: RepositoryCommandSnapshot): boolean {
+  assertMutationEvidenceComparable(before, after);
   return before.head !== after.head || before.branch !== after.branch || before.refsHash !== after.refsHash || changedSnapshotPaths(before, after).length > 0;
 }

package/src/cli/repositories/runtime-storage.ts

@@ -49,6 +49,7 @@ interface RuntimeStorageSpec {
   name: string;
   sourceName: string;
   controllerName: string;
+  sourceRoot?: 'harness' | 'forge';
   preserveNonEmpty?: boolean;
   detectActiveRuns?: boolean;
   detectActiveLocalJobs?: boolean;
@@ -68,6 +69,15 @@ const RUNTIME_STORAGE_SPECS: RuntimeStorageSpec[] = [
   { name: 'mcp', sourceName: 'mcp', controllerName: 'mcp' },
   { name: 'local-bridge', sourceName: 'local-bridge', controllerName: 'local-bridge' },
   { name: 'ephemeral-issues', sourceName: 'ephemeral-issues', controllerName: 'ephemeral-issues' },
+  // Legacy callers may still use these repository-relative paths, but the
+  // physical state is Controller Home-owned. Keep them as compatibility links
+  // until the corresponding adapters consume Controller paths directly.
+  { name: 'session', sourceName: 'session', controllerName: 'session' },
+  { name: 'planning', sourceName: 'planning', controllerName: 'planning' },
+  { name: 'security', sourceName: 'security', controllerName: 'security' },
+  { name: 'transfers', sourceName: 'transfers', controllerName: 'transfers' },
+  { name: 'browser-provider', sourceName: 'browser', controllerName: 'browser', sourceRoot: 'forge' },
+  { name: 'interaction-sessions', sourceName: 'interactions', controllerName: 'interactions', sourceRoot: 'forge' },
 ];
 
 function directoryEntries(path: string): string[] {
@@ -257,12 +267,14 @@ function legacyRuntimeBlocker(repositoryPath: string, spec: RuntimeStorageSpec):
 }
 
 function bindRuntimeDirectory(
+  repositoryRoot: string,
   harnessRoot: string,
   controllerRoot: string,
   repoId: string,
   spec: RuntimeStorageSpec,
 ): RuntimeStorageBinding {
-  const repositoryPath = join(harnessRoot, spec.sourceName);
+  const sourceRoot = spec.sourceRoot === 'forge' ? join(repositoryRoot, '.forge') : harnessRoot;
+  const repositoryPath = join(sourceRoot, spec.sourceName);
   const controllerPath = join(controllerRoot, spec.controllerName);
   mkdirSync(controllerPath, { recursive: true });
   writeOwnerMarker(controllerPath, repoId, spec.name);
@@ -378,6 +390,19 @@ function bindRuntimeDirectory(
   return { name: spec.name, repositoryPath, controllerPath, status: 'migrated' };
 }
 
+export function ensureRepositoryRuntimeStorageBinding(
+  repository: RepositoryRecord,
+  name: string,
+  controllerHome?: string,
+): RuntimeStorageBinding {
+  const spec = RUNTIME_STORAGE_SPECS.find((entry) => entry.name === name);
+  if (!spec) throw new Error(`RUNTIME_STORAGE_BINDING_UNKNOWN: ${name}`);
+  const controllerRoot = ensureRepositoryControllerLayout(controllerHome ?? '', repository.repoId);
+  const harnessRoot = join(repository.canonicalRoot, '.ai', 'harness');
+  mkdirSync(harnessRoot, { recursive: true });
+  return bindRuntimeDirectory(repository.canonicalRoot, harnessRoot, controllerRoot, repository.repoId, spec);
+}
+
 export function ensureRepositoryRuntimeStorage(
   repository: RepositoryRecord,
   controllerHome?: string,
@@ -386,7 +411,7 @@ export function ensureRepositoryRuntimeStorage(
   const harnessRoot = join(repository.canonicalRoot, '.ai', 'harness');
   mkdirSync(harnessRoot, { recursive: true });
 
-  const bindings = RUNTIME_STORAGE_SPECS.map((spec) => bindRuntimeDirectory(harnessRoot, controllerRoot, repository.repoId, spec));
+  const bindings = RUNTIME_STORAGE_SPECS.map((spec) => bindRuntimeDirectory(repository.canonicalRoot, harnessRoot, controllerRoot, repository.repoId, spec));
   const warnings = bindings
     .filter((binding) => binding.status === 'legacy-active' || binding.status === 'conflict')
     .map((binding) => `${binding.name}: ${binding.message ?? binding.status}`);

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

@@ -2,16 +2,18 @@ import { createHash } from 'crypto';
 import { existsSync, readFileSync } from 'fs';
 import { join, relative, resolve } from 'path';
 import {
+  adoptEditSessionSuccessorHead,
   applyEditOperations,
   beginEditSession,
   getEditSession,
-  type EditOperation,
   type EditSession,
   type EditSessionBinding,
   type EditSessionPatchError,
 } from '../editing/edit-session';
+import { normalizeEditOperation, type EditOperation } from '../editing/edit-operation-contract';
 import { getMcpPolicy } from '../mcp/policy';
 import type { RepositoryRecord } from './types';
+import { ensureRepositoryRuntimeStorageBinding } from './runtime-storage';
 
 export interface SafePatchFingerprint {
   path: string;
@@ -100,46 +102,15 @@ function objectEntries(value: unknown): Record<string, unknown>[] {
   return value.filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null && !Array.isArray(entry));
 }
 
-function normalizeReplacement(value: unknown): Array<{ oldText: string; newText: string; replaceAll?: boolean }> {
-  return objectEntries(value).map((replacement) => ({
-    oldText: String(replacement.old_text ?? replacement.oldText ?? ''),
-    newText: String(replacement.new_text ?? replacement.newText ?? ''),
-    replaceAll: replacement.replace_all === true || replacement.replaceAll === true,
-  }));
-}
-
 function normalizeOperation(entry: Record<string, unknown>, originalIndex: number): NormalizedOperation {
-  const type = String(entry.type ?? '');
   const path = String(entry.path ?? '').trim();
-  const expectedSha256 = String(entry.expected_sha256 ?? entry.expectedSha256 ?? '').trim();
   if (!path) throw new Error(`SAFE_PATCH_OPERATION_INVALID: operation ${originalIndex + 1} path is required`);
-  if (type === 'create') return { type, path, content: String(entry.content ?? ''), __originalIndex: originalIndex };
-  if (type === 'delete') return { type, path, expectedSha256, __originalIndex: originalIndex };
-  if (type === 'write') return { type, path, expectedSha256, content: String(entry.content ?? ''), __originalIndex: originalIndex };
-  if (type === 'replace') {
-    const replacements = Array.isArray(entry.replacements)
-      ? normalizeReplacement(entry.replacements)
-      : (entry.old_text !== undefined || entry.oldText !== undefined)
-        ? normalizeReplacement([entry])
-        : [];
-    if (replacements.length === 0) {
-      throw new Error(`SAFE_PATCH_OPERATION_INVALID: operation ${originalIndex + 1} replace requires replacements[] or old_text/new_text`);
-    }
-    return { type, path, expectedSha256, replacements, __originalIndex: originalIndex };
-  }
-  if (type === 'insert_before' || type === 'insert_after') {
-    return {
-      type,
-      path,
-      expectedSha256,
-      anchor: String(entry.anchor ?? ''),
-      content: String(entry.content ?? ''),
-      occurrence: typeof entry.occurrence === 'number' ? Math.trunc(entry.occurrence) : undefined,
-      __originalIndex: originalIndex,
-    };
+  try {
+    return { ...normalizeEditOperation({ ...entry, path }), __originalIndex: originalIndex } as NormalizedOperation;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`SAFE_PATCH_OPERATION_INVALID: operation ${originalIndex + 1} ${message}`);
   }
-  if (type === 'prepend' || type === 'append') return { type, path, expectedSha256, content: String(entry.content ?? ''), __originalIndex: originalIndex };
-  throw new Error(`SAFE_PATCH_OPERATION_INVALID: operation ${originalIndex + 1} has invalid type: ${type}`);
 }
 
 export function normalizeSafePatchOperations(value: unknown): EditOperation[] {
@@ -348,6 +319,10 @@ export function applySafePatch(repository: RepositoryRecord, input: {
   recoverStaleSession?: unknown;
   binding?: EditSessionBinding;
 }): SafePatchApplyResult {
+  const editStorage = ensureRepositoryRuntimeStorageBinding(repository, 'edit-sessions');
+  if (editStorage.status === 'legacy-active' || editStorage.status === 'conflict') {
+    throw new Error(`SAFE_PATCH_EDIT_SESSION_STORAGE_NOT_READY: ${editStorage.message ?? editStorage.status}`);
+  }
   const operations = normalizedSafePatchOperations(input.operations);
   if (operations.length === 0) throw new Error('SAFE_PATCH_OPERATIONS_REQUIRED: provide at least one operation');
   const size = chunkSize(input.chunkSize);
@@ -381,7 +356,28 @@ export function applySafePatch(repository: RepositoryRecord, input: {
       session = applyEditOperations(repository.canonicalRoot, policy, session.sessionId, preflight.operations.map(stripInternalIndex), { expectedRevision, maxBatchOperations: MAX_SAFE_PATCH_CHUNK_SIZE, binding: input.binding });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
-      if (!sessionId && input.recoverStaleSession !== false && message.includes('EDIT_SESSION_FINGERPRINT_STALE')) {
+      if (sessionId && input.recoverStaleSession !== false && message.includes('EDIT_SESSION_BASE_REVISION_CHANGED')) {
+        const previousSessionId = session.sessionId;
+        try {
+          session = adoptEditSessionSuccessorHead(repository.canonicalRoot, session.sessionId, { binding: input.binding });
+          expectedRevision = session.currentRevision;
+          recoveredSession = { reason: 'Existing Work-bound edit session adopted a proven non-overlapping successor HEAD.', previousSessionId, newSessionId: session.sessionId };
+          const retry = preflightChunk(repository, group, chunkIndex, refresh);
+          if (retry.failures.length === 0) {
+            session = applyEditOperations(repository.canonicalRoot, policy, session.sessionId, retry.operations.map(stripInternalIndex), { expectedRevision, maxBatchOperations: MAX_SAFE_PATCH_CHUNK_SIZE, binding: input.binding });
+          } else {
+            failures.push(...retry.failures);
+            failedChunk = chunkIndex;
+            if (!continueOnError) break;
+            continue;
+          }
+        } catch (adoptionError) {
+          failures.push(...patchErrorFailures(adoptionError, chunkIndex));
+          failedChunk = chunkIndex;
+          if (!continueOnError) break;
+          continue;
+        }
+      } else if (!sessionId && input.recoverStaleSession !== false && message.includes('EDIT_SESSION_FINGERPRINT_STALE')) {
         const previousSessionId = session.sessionId;
         session = beginEditSession(repository.canonicalRoot, { purpose: `${String(input.purpose ?? 'Safe repository patch').trim() || 'Safe repository patch'} (recovered)`, allowedPaths, binding: input.binding });
         expectedRevision = session.currentRevision;

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

@@ -4,6 +4,7 @@ import { join, relative, resolve } from 'path';
 import { capProcessOutput, redactProcessOutput } from '../../effects/process-runner';
 import { buildPatchHandoffArtifact } from '../../runtime/recovery/patch-handoff';
 import { executeRepositoryGitCommand, type RepositoryGitExecution } from './git-command-executor';
+import { resolveRepositoryGitCommitScope } from './structured-git';
 import { withControllerLock } from './locks';
 import type { RepositoryRecord } from './types';
 
@@ -32,6 +33,16 @@ export interface SelectedPathCommitResult {
   error?: { code: string; message: string };
 }
 
+export interface SelectedPathBeforeCommitGuardInput {
+  repository: RepositoryRecord;
+  requestedPaths: string[];
+  stagedPaths: string[];
+  /** Exact HEAD observed after staging and immediately before the physical commit. */
+  currentHead: string | null;
+}
+
+export type SelectedPathBeforeCommitGuard = (input: SelectedPathBeforeCommitGuardInput) => void;
+
 export interface TransferArtifactPreview {
   path: string;
   exists: boolean;
@@ -249,9 +260,12 @@ export function stageSelectedPaths(
 export function commitSelectedPaths(
   controllerHome: string,
   repository: RepositoryRecord,
-  input: { paths: unknown; message: unknown },
+  input: { paths: unknown; message: unknown; beforeCommitGuard?: SelectedPathBeforeCommitGuard },
 ): SelectedPathCommitResult {
-  const paths = normalizeSelectedPaths(repository, input.paths);
+  const selectedPaths = normalizeSelectedPaths(repository, input.paths);
+  const scope = resolveRepositoryGitCommitScope(repository, { paths: selectedPaths });
+  if (scope.source !== 'explicit_paths') throw new Error('SELECTED_PATH_COMMIT_SCOPE_INVALID: selected-path commit requires explicit path scope');
+  const paths = scope.paths;
   const message = String(input.message ?? '').trim();
   if (!message) throw new Error('COMMIT_MESSAGE_REQUIRED: message is required');
 
@@ -283,6 +297,12 @@ export function commitSelectedPaths(
     };
   }
 
+  // The repository layer owns staging and exact staged-path discovery, but it
+  // does not own Work lifecycle/review policy. Callers may inject one typed
+  // fail-closed guard at the last safe boundary before the physical commit.
+  const currentHead = gitText(repository, ['rev-parse', '--verify', 'HEAD']) || null;
+  input.beforeCommitGuard?.({ repository, requestedPaths: paths, stagedPaths: staged, currentHead });
+
   const commit = executeRepositoryGitCommand(controllerHome, repository, {
     args: ['commit', '--only', '-m', message, '--', ...paths],
     authorization: 'explicit_user_request',

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

@@ -1,4 +1,7 @@
 import { spawnSync } from 'child_process';
+import { randomUUID } from 'crypto';
+import { existsSync, readFileSync, renameSync, rmSync, writeFileSync } from 'fs';
+import { isAbsolute, resolve } from 'path';
 import { capProcessOutput, redactProcessOutput } from '../../effects/process-runner';
 import { executeRepositoryGitCommand, type RepositoryGitExecution } from './git-command-executor';
 import { validateBranchName } from './branch-name-policy';
@@ -51,6 +54,11 @@ export interface RepositoryGitCommitResult {
   error?: { code: string; message: string };
 }
 
+export interface RepositoryGitCommitScope {
+  source: 'explicit_paths' | 'staged_index';
+  paths: string[];
+}
+
 export interface RepositoryGitFinishResult {
   repoId: string;
   checkoutId: string;
@@ -90,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' });
@@ -114,6 +132,28 @@ function normalizePaths(input: unknown): string[] {
   return [...new Set(input.map((entry) => String(entry ?? '').trim().replace(/\\/g, '/')).filter(Boolean))].sort();
 }
 
+export function repositoryGitStagedPaths(repository: RepositoryRecord): string[] {
+  const staged = runGit(repository, ['diff', '--cached', '--name-only', '-z'], 128 * 1024);
+  if (!staged.ok) {
+    throw new Error(`GIT_COMMIT_SCOPE_INSPECTION_FAILED: ${staged.stderr || 'Unable to inspect the staged Git index.'}`);
+  }
+  return staged.stdout.split('\0').map((path) => path.trim()).filter(Boolean).sort();
+}
+
+/**
+ * Commit scope has one repository authority. Explicit pathspecs narrow the
+ * transaction; otherwise the exact staged Git index is the scope. Callers do
+ * not need to restate the same staged paths merely to satisfy routing policy.
+ */
+export function resolveRepositoryGitCommitScope(
+  repository: RepositoryRecord,
+  input: { paths?: unknown },
+): RepositoryGitCommitScope {
+  const explicitPaths = normalizePaths(input.paths);
+  if (explicitPaths.length > 0) return { source: 'explicit_paths', paths: explicitPaths };
+  return { source: 'staged_index', paths: repositoryGitStagedPaths(repository) };
+}
+
 function splitStatus(porcelain: string): { staged: string[]; unstaged: string[]; untracked: string[] } {
   const staged: string[] = [];
   const unstaged: string[] = [];
@@ -262,57 +302,108 @@ export function repositoryGitDeleteBranch(controllerHome: string, repository: Re
 export function repositoryGitCommit(controllerHome: string, repository: RepositoryRecord, input: { message: unknown; paths?: unknown; allowEmpty?: unknown; authorizationDecision?: AuthorizationDecision; sessionId?: string; principalId?: string; workId?: string; goalId?: string }): RepositoryGitCommitResult {
   const before = repositoryGitStatus(repository);
   const message = normalizeCommitMessage(input.message);
-  const paths = normalizePaths(input.paths);
+  const scope = resolveRepositoryGitCommitScope(repository, { paths: input.paths });
+  const paths = scope.source === 'explicit_paths' ? scope.paths : [];
   let stage: RepositoryGitExecution | undefined;
-  if (paths.length > 0) {
+  let explicitIndexSnapshot: { path: string; existed: boolean; contents?: Buffer } | undefined;
+  const restoreExplicitIndex = (): { ok: boolean; message?: string } => {
+    if (!explicitIndexSnapshot) return { ok: true };
+    const restorePath = `${explicitIndexSnapshot.path}.forge-restore-${randomUUID()}`;
+    try {
+      if (!explicitIndexSnapshot.existed) {
+        rmSync(explicitIndexSnapshot.path, { force: true });
+        return { ok: true };
+      }
+      if (!explicitIndexSnapshot.contents) return { ok: false, message: 'pre-stage index contents are unavailable' };
+      writeFileSync(restorePath, explicitIndexSnapshot.contents);
+      renameSync(restorePath, explicitIndexSnapshot.path);
+      return { ok: true };
+    } catch (error) {
+      rmSync(restorePath, { force: true });
+      return { ok: false, message: error instanceof Error ? error.message : String(error) };
+    }
+  };
+  const failedAfterExplicitStage = (code: string, message: string, commit?: RepositoryGitExecution): RepositoryGitCommitResult => {
+    const restored = restoreExplicitIndex();
+    return {
+      repoId: repository.repoId,
+      checkoutId: repository.activeCheckoutId,
+      before,
+      ...(stage ? { stage } : {}),
+      ...(commit ? { commit } : {}),
+      after: repositoryGitStatus(repository),
+      committed: false,
+      error: restored.ok
+        ? { code, message }
+        : { code: `${code}_INDEX_RESTORE_FAILED`, message: `${message}; failed to restore the exact pre-stage index: ${restored.message}` },
+    };
+  };
+  if (scope.source === 'explicit_paths') {
+    const rawIndexPath = gitText(repository, ['rev-parse', '--git-path', 'index']);
+    if (!rawIndexPath) {
+      return {
+        repoId: repository.repoId,
+        checkoutId: repository.activeCheckoutId,
+        before,
+        after: repositoryGitStatus(repository),
+        committed: false,
+        error: { code: 'GIT_INDEX_SNAPSHOT_FAILED', message: 'Unable to resolve the Git index path before an explicit-path commit.' },
+      };
+    }
+    const indexPath = isAbsolute(rawIndexPath) ? rawIndexPath : resolve(repository.canonicalRoot, rawIndexPath);
+    try {
+      const existed = existsSync(indexPath);
+      explicitIndexSnapshot = {
+        path: indexPath,
+        existed,
+        ...(existed ? { contents: readFileSync(indexPath) } : {}),
+      };
+    } catch (error) {
+      return {
+        repoId: repository.repoId,
+        checkoutId: repository.activeCheckoutId,
+        before,
+        after: repositoryGitStatus(repository),
+        committed: false,
+        error: { code: 'GIT_INDEX_SNAPSHOT_FAILED', message: error instanceof Error ? error.message : String(error) },
+      };
+    }
     stage = executeRepositoryGitCommand(controllerHome, repository, { args: ['add', '--all', '--', ...paths], authorization: 'explicit_user_request', ...input });
     if (stage.status !== 'executed' || stage.ok !== true) {
-      return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, before, stage, after: repositoryGitStatus(repository), committed: false, error: { code: 'GIT_STAGE_FAILED', message: stage.stderr || 'git add failed' } };
+      return failedAfterExplicitStage('GIT_STAGE_FAILED', stage.stderr || 'git add failed');
     }
   }
   const diffCheck = runGit(repository, ['diff', '--cached', '--quiet'], 64 * 1024);
   if (diffCheck.status === 0 && input.allowEmpty !== true) {
-    return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, before, stage, after: repositoryGitStatus(repository), committed: false, error: { code: 'GIT_NOTHING_STAGED', message: 'No staged changes to commit. Pass paths to stage, or allow_empty=true for an empty commit.' } };
+    return failedAfterExplicitStage('GIT_NOTHING_STAGED', 'No staged changes to commit. Pass paths to stage, or allow_empty=true for an empty commit.');
   }
   const mergeInProgress = runGit(repository, ['rev-parse', '--verify', 'MERGE_HEAD'], 64 * 1024).ok;
   if (mergeInProgress) {
     const unresolved = runGit(repository, ['diff', '--name-only', '--diff-filter=U', '-z'], 128 * 1024);
     const unresolvedPaths = unresolved.stdout.split('\0').map((path) => path.trim()).filter(Boolean);
     if (!unresolved.ok || unresolvedPaths.length > 0) {
-      return {
-        repoId: repository.repoId,
-        checkoutId: repository.activeCheckoutId,
-        before,
-        stage,
-        after: repositoryGitStatus(repository),
-        committed: false,
-        error: { code: 'GIT_MERGE_UNRESOLVED', message: unresolvedPaths.length > 0 ? `Merge still has unresolved path(s): ${unresolvedPaths.join(', ')}` : unresolved.stderr || 'Unable to inspect unresolved merge paths.' },
-      };
+      return failedAfterExplicitStage(
+        'GIT_MERGE_UNRESOLVED',
+        unresolvedPaths.length > 0 ? `Merge still has unresolved path(s): ${unresolvedPaths.join(', ')}` : unresolved.stderr || 'Unable to inspect unresolved merge paths.',
+      );
     }
     if (paths.length > 0) {
       const stagedNames = runGit(repository, ['diff', '--cached', '--name-only', '-z'], 128 * 1024);
       if (!stagedNames.ok) {
-        return { repoId: repository.repoId, checkoutId: repository.activeCheckoutId, before, stage, after: repositoryGitStatus(repository), committed: false, error: { code: 'GIT_MERGE_STAGED_SCOPE_INSPECTION_FAILED', message: stagedNames.stderr || 'Unable to inspect the merge index.' } };
+        return failedAfterExplicitStage('GIT_MERGE_STAGED_SCOPE_INSPECTION_FAILED', stagedNames.stderr || 'Unable to inspect the merge index.');
       }
       const allowed = new Set(paths);
       const stagedPaths = stagedNames.stdout.split('\0').map((path) => path.trim()).filter(Boolean);
       const outsideScope = stagedPaths.filter((path) => !allowed.has(path));
       if (outsideScope.length > 0) {
-        return {
-          repoId: repository.repoId,
-          checkoutId: repository.activeCheckoutId,
-          before,
-          stage,
-          after: repositoryGitStatus(repository),
-          committed: false,
-          error: { code: 'GIT_MERGE_STAGED_SCOPE_MISMATCH', message: `Resolved merge index contains staged path(s) outside the requested commit scope: ${outsideScope.join(', ')}` },
-        };
+        return failedAfterExplicitStage('GIT_MERGE_STAGED_SCOPE_MISMATCH', `Resolved merge index contains staged path(s) outside the requested commit scope: ${outsideScope.join(', ')}`);
       }
     }
   }
   const commitArgs = ['commit', '-m', message, ...(input.allowEmpty === true ? ['--allow-empty'] : []), ...(!mergeInProgress && paths.length > 0 ? ['--only', '--', ...paths] : [])];
   const commit = executeRepositoryGitCommand(controllerHome, repository, { args: commitArgs, authorization: 'explicit_user_request', ...input });
   const ok = commit.status === 'executed' && commit.ok === true;
+  if (!ok) return failedAfterExplicitStage('GIT_COMMIT_FAILED', commit.stderr || 'git commit failed', commit);
   return {
     repoId: repository.repoId,
     checkoutId: repository.activeCheckoutId,
@@ -320,8 +411,7 @@ export function repositoryGitCommit(controllerHome: string, repository: Reposito
     ...(stage ? { stage } : {}),
     commit,
     after: repositoryGitStatus(repository),
-    committed: ok,
-    ...(ok ? {} : { error: { code: 'GIT_COMMIT_FAILED', message: commit.stderr || 'git commit failed' } }),
+    committed: true,
   };
 }
 
@@ -334,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))) {
@@ -346,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) {
@@ -362,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 });
@@ -388,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();