@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -135,9 +135,115 @@ export function rollbackStoppedRepoLocalControllerHomeStorage(migration: Control
   renameSync(physicalHome, logicalHome);
 }
 
+
+export interface StoppedControllerHomeAuthorityRelocation {
+  migrated: boolean;
+  sourceHome: string;
+  destinationHome: string;
+  archivedDestinationHome?: string;
+}
+
+function directoryEntryExists(path: string): boolean {
+  try { lstatSync(path); return true; } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+/**
+ * Atomically relocate one fully stopped Controller Home to a new durable path.
+ * The caller owns liveness fencing and must prove Runtime, Connector, Recovery
+ * Gateway, Recovery Watchdog, and any other writers are stopped before calling.
+ *
+ * Existing destination contents are never merged. A caller that has already
+ * proven the destination is an authority-free shell may request archival; the
+ * entire shell is renamed aside so rollback can restore it byte-for-byte.
+ */
+export function relocateStoppedControllerHomeAuthority(input: {
+  sourceHome: string;
+  destinationHome: string;
+  archiveExistingDestination?: boolean;
+  archiveSuffix?: string;
+}): StoppedControllerHomeAuthorityRelocation {
+  const sourceHome = resolve(input.sourceHome);
+  const destinationHome = resolve(input.destinationHome);
+  if (sourceHome === destinationHome) throw new Error('CONTROLLER_HOME_RELOCATION_SAME_HOME');
+  if (!directoryEntryExists(sourceHome)) throw new Error(`CONTROLLER_HOME_RELOCATION_SOURCE_MISSING: ${sourceHome}`);
+  const sourceStat = lstatSync(sourceHome);
+  if (!sourceStat.isDirectory() || sourceStat.isSymbolicLink()) {
+    throw new Error(`CONTROLLER_HOME_RELOCATION_SOURCE_UNSUPPORTED: ${sourceHome}`);
+  }
+  mkdirSync(dirname(destinationHome), { recursive: true });
+
+  let archivedDestinationHome: string | undefined;
+  if (directoryEntryExists(destinationHome)) {
+    const destinationStat = lstatSync(destinationHome);
+    if (!destinationStat.isDirectory() || destinationStat.isSymbolicLink()) {
+      throw new Error(`CONTROLLER_HOME_RELOCATION_DESTINATION_UNSUPPORTED: ${destinationHome}`);
+    }
+    if (!input.archiveExistingDestination) {
+      throw new Error(`CONTROLLER_HOME_RELOCATION_DESTINATION_EXISTS: ${destinationHome}`);
+    }
+    const suffix = input.archiveSuffix?.trim() || `${Date.now()}-${process.pid}`;
+    if (!/^[A-Za-z0-9._-]{1,120}$/.test(suffix)) throw new Error('CONTROLLER_HOME_RELOCATION_ARCHIVE_SUFFIX_INVALID');
+    archivedDestinationHome = `${destinationHome}.pre-migration-${suffix}`;
+    if (directoryEntryExists(archivedDestinationHome)) {
+      throw new Error(`CONTROLLER_HOME_RELOCATION_ARCHIVE_EXISTS: ${archivedDestinationHome}`);
+    }
+    renameSync(destinationHome, archivedDestinationHome);
+  }
+
+  try {
+    renameSync(sourceHome, destinationHome);
+    if (directoryEntryExists(sourceHome) || !lstatSync(destinationHome).isDirectory()) {
+      throw new Error('CONTROLLER_HOME_RELOCATION_POSTCHECK_FAILED');
+    }
+    return {
+      migrated: true,
+      sourceHome,
+      destinationHome,
+      ...(archivedDestinationHome ? { archivedDestinationHome } : {}),
+    };
+  } catch (error) {
+    try {
+      if (!directoryEntryExists(sourceHome) && directoryEntryExists(destinationHome)) renameSync(destinationHome, sourceHome);
+      if (archivedDestinationHome && !directoryEntryExists(destinationHome) && directoryEntryExists(archivedDestinationHome)) {
+        renameSync(archivedDestinationHome, destinationHome);
+      }
+    } catch {
+      throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    throw error;
+  }
+}
+
+/** Caller must keep all Controller Home writers stopped until rollback completes. */
+export function rollbackStoppedControllerHomeAuthorityRelocation(
+  relocation: StoppedControllerHomeAuthorityRelocation,
+): void {
+  if (!relocation.migrated) return;
+  const sourceHome = resolve(relocation.sourceHome);
+  const destinationHome = resolve(relocation.destinationHome);
+  const archivedDestinationHome = relocation.archivedDestinationHome ? resolve(relocation.archivedDestinationHome) : undefined;
+  if (directoryEntryExists(sourceHome)) throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_SOURCE_EXISTS: ${sourceHome}`);
+  if (!directoryEntryExists(destinationHome) || !lstatSync(destinationHome).isDirectory()) {
+    throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_DESTINATION_MISSING: ${destinationHome}`);
+  }
+  if (archivedDestinationHome && !directoryEntryExists(archivedDestinationHome)) {
+    throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_ARCHIVE_MISSING: ${archivedDestinationHome}`);
+  }
+  renameSync(destinationHome, sourceHome);
+  try {
+    if (archivedDestinationHome) renameSync(archivedDestinationHome, destinationHome);
+  } catch (error) {
+    try { if (!directoryEntryExists(destinationHome) && directoryEntryExists(sourceHome)) renameSync(sourceHome, destinationHome); } catch { /* best effort */ }
+    throw new Error(`CONTROLLER_HOME_RELOCATION_ROLLBACK_RESTORE_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 export function ensureControllerHome(explicit?: string): string {
   const home = ensureControllerHomeStorage(resolveControllerHome(explicit));
-  for (const child of ['', 'repositories', 'system', 'locks', 'indexes', 'audit', 'mcp', 'sessions', 'work-handles']) {
+  for (const child of ['', 'repositories', 'system', 'locks', 'indexes', 'audit', 'mcp', 'sessions', 'work-handles', 'workflows']) {
     mkdirSync(join(home, child), { recursive: true });
   }
   return home;
@@ -147,7 +253,21 @@ 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 {
+  return join(resolveControllerHome(controllerHome), 'workflows');
+}
+
+export function ensureControllerWorkflowContentRoot(controllerHome: string): string {
+  const root = controllerWorkflowContentRoot(ensureControllerHome(controllerHome));
+  mkdirSync(root, { recursive: true });
+  return root;
+}
 
 export function controllerSystemRoot(controllerHome: string): string {
   return join(resolveControllerHome(controllerHome), 'system');
@@ -166,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 [
@@ -178,6 +343,7 @@ export function ensureRepositoryControllerLayout(controllerHome: string, repoId:
     'indexes',
     'edit-sessions',
     'controller',
+    'hook-state',
     'local-bridge',
     'ephemeral-issues',
     'work-handles',

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/identity.ts

@@ -39,6 +39,19 @@ export function stableRemoteRepoId(canonicalRemote: string): string {
   return `repo_${digest(`remote\0${canonicalRemote}`).slice(0, 24)}`;
 }
 
+/** Portable Project identity: stable across ForgeInstance/repository registrations for the same canonical remote. */
+export function stablePortableProjectId(canonicalRemote: string): string {
+  const normalized = normalizeRemoteUrl(canonicalRemote);
+  if (!normalized) throw new Error('PROJECT_REMOTE_IDENTITY_REQUIRED');
+  return `project_${digest(`project\0${normalized}`).slice(0, 24)}`;
+}
+
+export function portableProjectSourceFingerprint(canonicalRemote: string): string {
+  const normalized = normalizeRemoteUrl(canonicalRemote);
+  if (!normalized) throw new Error('PROJECT_REMOTE_IDENTITY_REQUIRED');
+  return digest(`project-source\0${normalized}`);
+}
+
 export function newLocalRepoId(): string {
   return `repo_local_${randomUUID().replace(/-/g, '')}`;
 }

package/src/cli/repositories/registry.ts

@@ -1,12 +1,12 @@
 import { spawnSync } from 'child_process';
 import {
-  appendFileSync,
   existsSync,
   mkdirSync,
   readFileSync,
   realpathSync,
   renameSync,
   rmSync,
+  statSync,
   writeFileSync,
 } from 'fs';
 import { dirname, join, relative, resolve } from 'path';
@@ -17,6 +17,7 @@ import {
   ensureControllerHome,
   ensureRepositoryControllerLayout,
 } from './controller-home';
+import { withControllerLock } from './locks';
 import {
   inferDisplayName,
   newLocalRepoId,
@@ -38,7 +39,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 +219,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);
 }
@@ -272,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;
@@ -336,9 +401,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 +437,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 +478,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';
@@ -540,17 +601,39 @@ 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';
+
+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(
@@ -560,10 +643,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,
@@ -599,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,
@@ -623,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}`);
   }
@@ -645,13 +744,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 +767,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 +779,6 @@ export function registerRepository(input: RegisterRepositoryInput): RepositoryRe
   ];
   saveRepositoryRegistry(registry, home);
   ensureRepositoryControllerLayout(home, repoId);
-  writeLocalIdentity(record);
   return record;
 }
 
@@ -748,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 = {
@@ -764,21 +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);
-  ensureHarnessRuntimeIgnored(canonicalRoot);
-  atomicJson(join(canonicalRoot, LOCAL_CONFIG), {
-    schemaVersion: 1,
-    repoId: next.repoId,
-    checkoutId,
-    stateStorageStrategy: next.stateStorageStrategy,
-  });
-  return next;
+  return activate ? selectRepositoryCheckout(next, checkoutId) : next;
 }
 
 export function setRepositoryCheckoutLifecycle(input: SetRepositoryCheckoutLifecycleInput): RepositoryRecord {
@@ -868,7 +955,6 @@ export function updateRepository(repoId: string, patch: UpdateRepositoryInput, c
   };
   registry.repositories[index] = next;
   saveRepositoryRegistry(registry, controllerHome);
-  writeLocalIdentity(next);
   return next;
 }
 
@@ -993,13 +1079,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;
 }