@moretea-labs/forge 1.7.2 → 1.8.0

package/src/cli/repositories/registry.ts

@@ -1,6 +1,5 @@
 import { spawnSync } from 'child_process';
 import {
-  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
@@ -17,6 +16,7 @@ import {
   ensureControllerHome,
   ensureRepositoryControllerLayout,
 } from './controller-home';
+import { withControllerLock } from './locks';
 import {
   inferDisplayName,
   newLocalRepoId,
@@ -38,7 +38,7 @@ import type {
 
 const REGISTRY_FILE = 'repositories.json';
 const FOCUS_FILE = 'focus.json';
-const LOCAL_CONFIG = '.ai/harness/repository.json';
+const LEGACY_LOCAL_CONFIG = '.ai/harness/repository.json';
 const LEGACY_GITHUB_PLUGIN_CONFIG = '.forge/plugins/github.json';
 
 interface RegisterRepositoryInput {
@@ -218,6 +218,25 @@ function repositoryByGitCommonDirectory(records: RepositoryRecord[], root: strin
   return linkedWorktreeFallback ?? historicalCheckoutFallback;
 }
 
+/**
+ * Resolve an already-registered repository from one concrete checkout root
+ * without mutating Repository Registry state. Exact canonical/active-checkout
+ * matches stay filesystem-only; Git common-directory probing is a bounded
+ * compatibility fallback for linked worktrees that predate checkout tracking.
+ */
+export function findRegisteredRepositoryByCheckoutRoot(
+  root: string,
+  controllerHome?: string,
+): RepositoryRecord | undefined {
+  const candidateRoot = resolve(root);
+  const records = listRepositories(controllerHome).filter((record) => record.enabled !== false && !record.removedAt);
+  const exact = records.find((record) => (
+    comparablePath(record.canonicalRoot) === comparablePath(candidateRoot)
+    || activeCheckouts(record).some((checkout) => comparablePath(checkout.canonicalRoot) === comparablePath(candidateRoot))
+  ));
+  return exact ?? repositoryByGitCommonDirectory(records, candidateRoot);
+}
+
 function managedCheckoutMatchesRepository(record: RepositoryRecord, checkout: RepositoryCheckout): boolean {
   return repositoryCheckoutRootMatches(record, checkout.canonicalRoot);
 }
@@ -336,9 +355,27 @@ export function loadRepositoryRegistry(controllerHome?: string): RepositoryRegis
 
 export function saveRepositoryRegistry(registry: RepositoryRegistry, controllerHome?: string): RepositoryRegistry {
   const home = ensureControllerHome(registryHome(controllerHome));
-  const next = { ...registry, schemaVersion: 1 as const, updatedAt: now() };
-  atomicJson(join(home, REGISTRY_FILE), next);
-  return next;
+  return withControllerLock(
+    home,
+    { scope: 'global', resource: 'repository-registry' },
+    'repository-registry:save',
+    () => {
+      const path = join(home, REGISTRY_FILE);
+      const current = readRegistryFile(path, true);
+      if (current && current.updatedAt !== registry.updatedAt) {
+        throw new Error(
+          `REPOSITORY_REGISTRY_STALE: expected=${registry.updatedAt}; current=${current.updatedAt}; reload canonical Repository Registry and retry`,
+        );
+      }
+      const previousRevision = timestampValue(registry.updatedAt);
+      const updatedAt = new Date(Math.max(Date.now(), previousRevision + 1)).toISOString();
+      const next = { ...registry, schemaVersion: 1 as const, updatedAt };
+      atomicJson(path, next);
+      return next;
+    },
+    30_000,
+    5_000,
+  );
 }
 
 export function consolidateRepositoryRegistry(controllerHome?: string): RepositoryRegistry {
@@ -354,7 +391,7 @@ function resolveGitRoot(inputPath: string): string {
 }
 
 function readLocalIdentity(canonicalRoot: string): { repoId?: string } {
-  const path = join(canonicalRoot, LOCAL_CONFIG);
+  const path = join(canonicalRoot, LEGACY_LOCAL_CONFIG);
   if (!existsSync(path)) return {};
   try {
     const parsed = JSON.parse(readFileSync(path, 'utf-8')) as { repoId?: unknown };
@@ -395,28 +432,6 @@ function readLegacyGitHubPluginConfig(canonicalRoot: string): Partial<Repository
   }
 }
 
-function ensureHarnessRuntimeIgnored(canonicalRoot: string): void {
-  const gitExclude = git(canonicalRoot, ['rev-parse', '--git-path', 'info/exclude']);
-  if (!gitExclude) return;
-  const path = resolve(canonicalRoot, gitExclude);
-  const existing = existsSync(path) ? readFileSync(path, 'utf-8') : '';
-  if (existing.split(/\r?\n/).some((line) => line.trim() === '.ai/harness/')) return;
-  mkdirSync(dirname(path), { recursive: true });
-  const prefix = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
-  appendFileSync(path, `${prefix}# forge runtime metadata (controller-owned, never source)\n.ai/harness/\n`, 'utf-8');
-}
-
-function writeLocalIdentity(record: RepositoryRecord): void {
-  ensureHarnessRuntimeIgnored(record.canonicalRoot);
-  const path = join(record.canonicalRoot, LOCAL_CONFIG);
-  atomicJson(path, {
-    schemaVersion: 1,
-    repoId: record.repoId,
-    checkoutId: record.activeCheckoutId,
-    stateStorageStrategy: record.stateStorageStrategy,
-  });
-}
-
 function repositoryType(root: string, remoteUrl: string | undefined): RepositoryType {
   const bare = git(root, ['rev-parse', '--is-bare-repository']);
   if (bare === 'true') return 'bare';
@@ -553,6 +568,27 @@ export function getRepository(repoId: string, controllerHome?: string, options:
   return record;
 }
 
+export type RepositoryCheckoutSelectionErrorCode = 'CHECKOUT_NOT_FOUND' | 'CHECKOUT_NOT_ACTIVE';
+
+export class RepositoryCheckoutSelectionError extends Error {
+  readonly code: RepositoryCheckoutSelectionErrorCode;
+  readonly repoId: string;
+  readonly checkoutId: string;
+  readonly lifecycle?: RepositoryCheckoutLifecycle;
+
+  constructor(input: { code: RepositoryCheckoutSelectionErrorCode; repoId: string; checkoutId: string; lifecycle?: RepositoryCheckoutLifecycle }) {
+    const message = input.code === 'CHECKOUT_NOT_FOUND'
+      ? `checkout not found for ${input.repoId}: ${input.checkoutId}`
+      : `CHECKOUT_NOT_ACTIVE: ${input.repoId}/${input.checkoutId} is ${input.lifecycle ?? 'unknown'}`;
+    super(message);
+    this.name = 'RepositoryCheckoutSelectionError';
+    this.code = input.code;
+    this.repoId = input.repoId;
+    this.checkoutId = input.checkoutId;
+    this.lifecycle = input.lifecycle;
+  }
+}
+
 export function selectRepositoryCheckout(
   record: RepositoryRecord,
   checkoutId?: string,
@@ -560,10 +596,10 @@ export function selectRepositoryCheckout(
 ): RepositoryRecord {
   if (!checkoutId?.trim()) return record;
   const checkout = record.checkouts.find((candidate) => candidate.checkoutId === checkoutId.trim());
-  if (!checkout) throw new Error(`checkout not found for ${record.repoId}: ${checkoutId}`);
+  if (!checkout) throw new RepositoryCheckoutSelectionError({ code: 'CHECKOUT_NOT_FOUND', repoId: record.repoId, checkoutId: checkoutId.trim() });
   const lifecycle = repositoryCheckoutLifecycle(checkout);
   if (lifecycle !== 'active' && !(options.allowArchived === true && lifecycle === 'archived')) {
-    throw new Error(`CHECKOUT_NOT_ACTIVE: ${record.repoId}/${checkout.checkoutId} is ${lifecycle}`);
+    throw new RepositoryCheckoutSelectionError({ code: 'CHECKOUT_NOT_ACTIVE', repoId: record.repoId, checkoutId: checkout.checkoutId, lifecycle });
   }
   return {
     ...record,
@@ -645,13 +681,6 @@ export function registerRepository(input: RegisterRepositoryInput): RepositoryRe
     registry.repositories[index] = next;
     saveRepositoryRegistry(registry, home);
     ensureRepositoryControllerLayout(home, next.repoId);
-    ensureHarnessRuntimeIgnored(canonicalRoot);
-    atomicJson(join(canonicalRoot, LOCAL_CONFIG), {
-      schemaVersion: 1,
-      repoId: next.repoId,
-      checkoutId,
-      stateStorageStrategy: next.stateStorageStrategy,
-    });
     return selectRepositoryCheckout(next, checkoutId);
   }
 
@@ -675,7 +704,7 @@ export function registerRepository(input: RegisterRepositoryInput): RepositoryRe
     createdAt: existing?.createdAt ?? timestamp,
     updatedAt: timestamp,
     lastSeenAt: timestamp,
-    configurationPath: join(canonicalRoot, LOCAL_CONFIG),
+    configurationPath: registryPath(home),
     stateStorageStrategy: input.stateStorageStrategy ?? existing?.stateStorageStrategy ?? 'hybrid',
     disabledAt: enabled ? undefined : existing?.disabledAt,
     removedAt: enabled ? undefined : existing?.removedAt,
@@ -687,7 +716,6 @@ export function registerRepository(input: RegisterRepositoryInput): RepositoryRe
   ];
   saveRepositoryRegistry(registry, home);
   ensureRepositoryControllerLayout(home, repoId);
-  writeLocalIdentity(record);
   return record;
 }
 
@@ -771,13 +799,6 @@ export function addRepositoryCheckout(input: AddRepositoryCheckoutInput): Reposi
   };
   registry.repositories[index] = next;
   saveRepositoryRegistry(registry, home);
-  ensureHarnessRuntimeIgnored(canonicalRoot);
-  atomicJson(join(canonicalRoot, LOCAL_CONFIG), {
-    schemaVersion: 1,
-    repoId: next.repoId,
-    checkoutId,
-    stateStorageStrategy: next.stateStorageStrategy,
-  });
   return next;
 }
 
@@ -868,7 +889,6 @@ export function updateRepository(repoId: string, patch: UpdateRepositoryInput, c
   };
   registry.repositories[index] = next;
   saveRepositoryRegistry(registry, controllerHome);
-  writeLocalIdentity(next);
   return next;
 }
 
@@ -993,13 +1013,12 @@ export function refreshRepository(repoId: string, controllerHome?: string): Repo
     repositoryType: repositoryType(canonicalRoot, rawRemote),
     updatedAt: timestamp,
     lastSeenAt: timestamp,
-    configurationPath: join(canonicalRoot, LOCAL_CONFIG),
+    configurationPath: registryPath(home),
   };
   registry.repositories[index] = refreshed;
   registry.repositories = retireCanonicalDuplicates(registry.repositories, canonicalRoot, repoId, timestamp);
   saveRepositoryRegistry(registry, home);
   ensureRepositoryControllerLayout(home, repoId);
-  writeLocalIdentity(refreshed);
   return refreshed;
 }
 

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',