@moretea-labs/forge 1.7.2 → 1.8.1

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

@@ -1,10 +1,10 @@
 import { createHash } from 'crypto';
 import { spawnSync } from 'child_process';
-import { appendFileSync, mkdirSync } from 'fs';
-import { dirname, join } from 'path';
+import { appendFileSync, existsSync, lstatSync, mkdirSync } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
 import { capProcessOutput, redactProcessOutput } from '../../effects/process-runner';
 import { MAX_AGENT_TIMEOUT_MS, MIN_AGENT_TIMEOUT_MS } from '../controller/runtime-config';
-import { repositoryControllerRoot } from './controller-home';
+import { scopedOperationRoot } from './controller-home';
 import {
   classifyRepositoryCommand,
   type RepositoryCommandAuthorization,
@@ -13,6 +13,8 @@ import {
 import {
   assertCommandPathOperandsStayInRepository,
   assertRepositoryCommandInputAllowed,
+  commandExecutionScopeKey,
+  type RepositoryCommandScopeTarget,
   type RepositoryCommandExternalPathUsage,
   resolveRepositoryCommandCwd,
 } from './command-scope';
@@ -22,11 +24,12 @@ import type { RepositoryRecord } from './types';
 import { readRepositoryAccessPolicy } from '../../runtime/control-plane/governance/access-policy';
 import { invalidateRepositoryReadCaches } from '../repository/inspector';
 import { assertResolvedAuthorization, decideAuthorization, type AuthorizationDecision } from '../../runtime/control-plane/governance/authorization';
-import { assertRuntimeMayWriteOrThrow } from '../../runtime/root/write-fence';
+import { assertRuntimeMayWriteOrThrow, isRuntimeWriteFenceError } from '../../runtime/root/write-fence';
 import { commandEnvironment, runCanonicalCommand, type RepositoryCommandAsyncHooks, type SpawnCommandResult } from './command-process';
 import {
   changedSnapshotPaths,
   emptyWorkspaceSnapshot,
+  readonlyUnobservedRepositorySnapshot,
   repositorySnapshot,
   repositorySnapshotAsync,
   snapshotChanged,
@@ -76,11 +79,13 @@ export interface ExecuteRepositoryCommandInput {
   snapshotFingerprintTimeoutMs?: number;
 }
 
+export type { RepositoryCommandScopeTarget as RepositoryCommandExecutionTarget };
+
 
 export interface RepositoryCommandExecution {
   status: 'preview' | 'approval_required' | 'executed';
   repoId: string;
-  checkoutId: string;
+  checkoutId?: string;
   cwd: string;
   command: RepositoryCommandValue;
   classification: RepositoryCommandClassification;
@@ -138,8 +143,38 @@ function boundedInteger(value: number | undefined, fallback: number, minimum: nu
   return normalized;
 }
 
+function boundedSnapshotFingerprintPaths(
+  root: string,
+  cwd: string,
+  command: CanonicalRepositoryCommand,
+): string[] | undefined {
+  if (command.kind !== 'argv') return undefined;
+  const program = (command.executable ?? '').split(/[\\/]/).at(-1)?.toLowerCase().replace(/\.exe$/, '');
+  const args = [...(command.args ?? [])];
+  if (program !== 'git' || args[0]?.toLowerCase() !== 'add') return undefined;
+  const separator = args.indexOf('--');
+  if (separator < 0 || separator === args.length - 1) return undefined;
+  const operands = args.slice(separator + 1);
+  if (operands.length > 32) return undefined;
+
+  const paths: string[] = [];
+  for (const operand of operands) {
+    if (!operand || operand.includes('\0') || operand.startsWith(':') || /[*?\[\]]/.test(operand)) return undefined;
+    const absolute = resolve(cwd, operand);
+    const path = relative(root, absolute).replace(/\\/g, '/');
+    if (!path || path === '..' || path.startsWith('../')) return undefined;
+    try {
+      if (existsSync(absolute) && lstatSync(absolute).isDirectory()) return undefined;
+    } catch {
+      return undefined;
+    }
+    paths.push(path);
+  }
+  return [...new Set(paths)].sort();
+}
+
 function approvalToken(
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   relativeCwd: string,
   command: RepositoryCommandValue,
   classification: RepositoryCommandClassification,
@@ -148,7 +183,7 @@ function approvalToken(
 ): string {
   return createHash('sha256').update(JSON.stringify({
     version: 2,
-    repoId: repository.repoId,
+    repoId: commandExecutionScopeKey(repository),
     checkoutId: repository.activeCheckoutId,
     cwd: relativeCwd,
     command,
@@ -159,7 +194,7 @@ function approvalToken(
 }
 
 function finalizePreparedExecution(
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   input: ExecuteRepositoryCommandInput,
   controllerHome: string | undefined,
   root: string,
@@ -182,7 +217,7 @@ function finalizePreparedExecution(
 } {
   const commandForPersistence = commandValue(command);
   const token = approvalToken(repository, relativeCwd, commandForPersistence, classification, before, externalPathUsages);
-  const permission = controllerHome ? readRepositoryAccessPolicy(controllerHome, repository.repoId) : undefined;
+  const permission = controllerHome ? readRepositoryAccessPolicy(controllerHome, commandExecutionScopeKey(repository)) : undefined;
   const isGit = command.kind === 'argv'
     ? command.executable?.split(/[\\/]/).at(-1)?.toLowerCase() === 'git'
     : /^\s*git\s+/i.test(command.shellCommand!);
@@ -195,8 +230,8 @@ function finalizePreparedExecution(
     controllerHome,
     accessMode: permission?.mode ?? 'request',
     risk,
-    repositoryId: repository.repoId,
-    currentRepositoryId: repository.repoId,
+    repositoryId: commandExecutionScopeKey(repository),
+    currentRepositoryId: commandExecutionScopeKey(repository),
     permissionSnapshotVersion: permission?.revision ?? 1,
     approvalToken: token,
     command: commandForPersistence,
@@ -206,14 +241,14 @@ function finalizePreparedExecution(
     ...(input.workId ? { workId: input.workId, boundWorkId: input.workId } : {}),
   }) : undefined);
   const resolved = controllerHome && input.approvalRequestId
-    ? assertResolvedAuthorization({ controllerHome, repositoryId: repository.repoId, approvalRequestId: input.approvalRequestId, sessionId: input.sessionId, principalId: input.principalId, workId: input.workId, permissionSnapshotVersion: permission?.revision ?? 1, command: commandForPersistence })
+    ? assertResolvedAuthorization({ controllerHome, repositoryId: commandExecutionScopeKey(repository), approvalRequestId: input.approvalRequestId, sessionId: input.sessionId, principalId: input.principalId, workId: input.workId, permissionSnapshotVersion: permission?.revision ?? 1, command: commandForPersistence })
     : undefined;
   const effectiveDecision: AuthorizationDecision | undefined = resolved
     ? { decision: 'allow', source: 'user_confirmation', reason: 'Resolved approval request matches the exact command and current permission snapshot.' }
     : delegated;
   const execution: RepositoryCommandExecution = {
     status: input.dryRun === true ? 'preview' : 'approval_required',
-    repoId: repository.repoId,
+    repoId: commandExecutionScopeKey(repository),
     checkoutId: repository.activeCheckoutId,
     cwd: relativeCwd,
     command: commandForPersistence,
@@ -246,7 +281,7 @@ function finalizePreparedExecution(
 }
 
 function prepareRepositoryCommandExecution(
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   input: ExecuteRepositoryCommandInput,
   controllerHome?: string,
 ): {
@@ -265,7 +300,10 @@ function prepareRepositoryCommandExecution(
     allowOpaqueLocalScript: input.allowOpaqueLocalScript,
   });
   const externalGrants = loadExternalFilesystemGrants(root).grants;
-  const externalPathUsages = assertCommandPathOperandsStayInRepository(command, cwd, root, externalGrants);
+  const externalPathUsages = assertCommandPathOperandsStayInRepository(command, cwd, root, externalGrants, {
+    controllerHome,
+    repositoryId: commandExecutionScopeKey(repository),
+  });
   const classification = classifyRepositoryCommand(command, repository.defaultBranch);
   const before = input.reuseSnapshot ?? (input.allowNonGitWorkspace ? emptyWorkspaceSnapshot() : repositorySnapshot(root));
   return finalizePreparedExecution(
@@ -283,9 +321,10 @@ function prepareRepositoryCommandExecution(
 }
 
 async function prepareRepositoryCommandExecutionAsync(
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   input: ExecuteRepositoryCommandInput,
   controllerHome?: string,
+  mode: 'standard' | 'readonly_direct' = 'standard',
 ): Promise<{
   root: string;
   cwd: string;
@@ -302,17 +341,27 @@ async function prepareRepositoryCommandExecutionAsync(
     allowOpaqueLocalScript: input.allowOpaqueLocalScript,
   });
   const externalGrants = loadExternalFilesystemGrants(root).grants;
-  const externalPathUsages = assertCommandPathOperandsStayInRepository(command, cwd, root, externalGrants);
+  const externalPathUsages = assertCommandPathOperandsStayInRepository(command, cwd, root, externalGrants, {
+    controllerHome,
+    repositoryId: commandExecutionScopeKey(repository),
+  });
   const classification = classifyRepositoryCommand(command, repository.defaultBranch);
-  // A proven readonly direct/preview lane never compares before/after mutation.
-  // Skip per-path fingerprints there so a large dirty worktree cannot block a
-  // harmless read; write-capable lanes keep the strict fingerprint cap.
+  if (mode === 'readonly_direct' && classification.risk !== 'readonly') {
+    throw new Error(`READONLY_DIRECT_ROUTE_REQUIRED: received ${classification.risk}`);
+  }
+  // The readonly-direct lane has already resolved repository identity, cwd/path
+  // scope, command input and readonly classification. Mutation snapshots are not
+  // authorization authority, so do not launch rev-parse/branch/status/show-ref
+  // merely to prove that a command selected for this lane did not mutate state.
+  // Write-capable lanes keep their complete observed snapshot semantics.
   const before = input.reuseSnapshot ?? (input.allowNonGitWorkspace
     ? emptyWorkspaceSnapshot()
-    : await repositorySnapshotAsync(root, input.signal, {
-        pathFingerprints: !(classification.risk === 'readonly' && controllerHome === undefined),
-        fingerprintTimeoutMs: input.snapshotFingerprintTimeoutMs,
-      }));
+    : mode === 'readonly_direct'
+      ? readonlyUnobservedRepositorySnapshot()
+      : await repositorySnapshotAsync(root, input.signal, {
+          fingerprintTimeoutMs: input.snapshotFingerprintTimeoutMs,
+          fingerprintPaths: boundedSnapshotFingerprintPaths(root, cwd, command),
+        }));
   return finalizePreparedExecution(
     repository,
     input,
@@ -328,7 +377,7 @@ async function prepareRepositoryCommandExecutionAsync(
 }
 
 export function previewRepositoryCommandExecution(
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   input: ExecuteRepositoryCommandInput,
   controllerHome?: string,
 ): PreparedRepositoryCommandExecution {
@@ -342,7 +391,7 @@ export function previewRepositoryCommandExecution(
 
 /** Async preview — preferred on Fast Path to avoid blocking Gateway with sync git snapshots. */
 export async function previewRepositoryCommandExecutionAsync(
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   input: ExecuteRepositoryCommandInput,
   controllerHome?: string,
 ): Promise<PreparedRepositoryCommandExecution> {
@@ -356,10 +405,12 @@ export async function previewRepositoryCommandExecutionAsync(
 
 function auditCommand(
   controllerHome: string,
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   execution: RepositoryCommandExecution,
 ): void {
-  const path = join(repositoryControllerRoot(controllerHome, repository.repoId), 'audit', 'commands.jsonl');
+  // A workspace target has no repository semantics; its command audit belongs to
+  // the workspace partition, not a synthetic repository partition.
+  const path = join(scopedOperationRoot(controllerHome, commandExecutionScopeKey(repository)), 'audit', 'commands.jsonl');
   mkdirSync(dirname(path), { recursive: true });
   appendFileSync(path, `${JSON.stringify({
     timestamp: new Date().toISOString(),
@@ -371,7 +422,7 @@ function auditCommand(
 
 export function executeRepositoryCommand(
   controllerHome: string,
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   input: ExecuteRepositoryCommandInput,
 ): RepositoryCommandExecution {
   const prepared = prepareRepositoryCommandExecution(repository, input, controllerHome);
@@ -394,7 +445,7 @@ export function executeRepositoryCommand(
     try {
       assertRuntimeMayWriteOrThrow('remote_side_effect', controllerHome);
     } catch (error) {
-      if (error instanceof Error && error.message.startsWith('WRITER_FENCED:')) throw error;
+      if (isRuntimeWriteFenceError(error)) throw error;
       /* unbound legacy */
     }
   }
@@ -449,18 +500,19 @@ export function executeRepositoryCommand(
  *
  * This path exists for short repository reads that must remain available while
  * Runtime writer authority is fenced or rotating. It reuses the exact command
- * input/scope classifier, repository snapshots, bounded async process runner,
- * cancellation, environment allowlist, output caps and redaction, but it never
- * writes command audit state, Process records, Leases, Jobs or receipts.
+ * input/scope classifier, bounded async process runner, cancellation,
+ * environment allowlist, output caps and redaction. It deliberately owns no
+ * mutation snapshot or Controller write state, Process records, Leases, Jobs or receipts.
  */
 export async function executeRepositoryReadOnlyCommandDirect(
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   input: ExecuteRepositoryCommandInput,
 ): Promise<RepositoryCommandExecution> {
   const prepared = await prepareRepositoryCommandExecutionAsync(
     repository,
     { ...input, dryRun: false },
     undefined,
+    'readonly_direct',
   );
   const { root, cwd, command, timeoutMs, maxOutputBytes, before, execution: base, externalPathUsages } = prepared;
   if (base.classification.risk !== 'readonly') {
@@ -490,10 +542,9 @@ export async function executeRepositoryReadOnlyCommandDirect(
 
   const result = await runCanonicalCommand(command, cwd, timeoutMs, maxOutputBytes, { signal });
   // This entry point is reachable only after the bounded classifier has proven
-  // the command readonly. A second full repository snapshot would start four
-  // extra Git processes merely to rediscover the invariant we already used to
-  // select this lane. Keep the captured pre-execution snapshot as both sides of
-  // the receipt; write-capable lanes still take independent before/after snapshots.
+  // the command readonly. Mutation evidence is explicitly unobserved rather than
+  // fabricated: no before/after Git snapshot is taken, while write-capable lanes
+  // still take independent observed before/after snapshots.
   const after = before;
   return {
     ...base,
@@ -519,7 +570,7 @@ export async function executeRepositoryReadOnlyCommandDirect(
 
 export async function executeRepositoryCommandAsync(
   controllerHome: string,
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   input: ExecuteRepositoryCommandInput,
   hooks: RepositoryCommandAsyncHooks = {},
 ): Promise<RepositoryCommandExecution> {
@@ -576,6 +627,7 @@ export async function executeRepositoryCommandAsync(
     try {
       after = await repositorySnapshotAsync(root, signal?.aborted ? undefined : signal, {
         fingerprintTimeoutMs: input.snapshotFingerprintTimeoutMs,
+        fingerprintPaths: boundedSnapshotFingerprintPaths(root, cwd, command),
       });
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);

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

@@ -7,7 +7,7 @@ import { normalizeRepositoryCommand, type CanonicalRepositoryCommand } from './c
 
 const MAX_COMMAND_LENGTH = 32 * 1024;
 
-export type RepositoryCommandExternalPathOperation = 'external_read' | 'external_copy_into_workspace';
+export type RepositoryCommandExternalPathOperation = 'external_read' | 'external_copy_into_workspace' | 'controller_local_effect';
 
 export interface RepositoryCommandExternalPathUsage {
   token: string;
@@ -33,11 +33,34 @@ function nearestExistingPath(candidate: string): string | undefined {
   return current;
 }
 
+/**
+ * Minimal command execution target. Repository identity stays optional: an
+ * arbitrary workspace target carries only its scope key and root, so command
+ * policy/audit/cwd checks need no fabricated repository record.
+ */
+export interface RepositoryCommandScopeTarget {
+  canonicalRoot: string;
+  /** Registered repository id (`RepositoryRecord.repoId`); absent for an arbitrary workspace target. */
+  repoId?: string;
+  /** Workspace scope key; present only when the target is not a repository. */
+  workspaceScopeKey?: string;
+  activeCheckoutId?: string;
+  defaultBranch?: string;
+  enabled?: boolean;
+}
+
+/** Canonical scope key for command policy/audit/approval storage. */
+export function commandExecutionScopeKey(target: RepositoryCommandScopeTarget): string {
+  const key = target.repoId?.trim() || target.workspaceScopeKey?.trim();
+  if (!key) throw new Error('COMMAND_TARGET_SCOPE_REQUIRED: command target requires a repository id or workspace scope key');
+  return key;
+}
+
 export function resolveRepositoryCommandCwd(
-  repository: RepositoryRecord,
+  repository: RepositoryCommandScopeTarget,
   requestedCwd: string | undefined,
 ): { root: string; cwd: string; relativeCwd: string } {
-  if (!repository.enabled) throw new Error(`REPOSITORY_DISABLED: ${repository.repoId}`);
+  if (repository.enabled === false) throw new Error(`REPOSITORY_DISABLED: ${commandExecutionScopeKey(repository)}`);
   const root = realpathSync(repository.canonicalRoot);
   const raw = requestedCwd?.trim() || '.';
   if (raw.includes('\0')) throw new Error('COMMAND_SCOPE_DENIED: cwd contains a null byte');
@@ -154,11 +177,30 @@ export function assertRepositoryCommandStableHostIdentity(input: unknown): Canon
   return command;
 }
 
+function assertNoUnmanagedControllerWorktreeLifecycle(command: CanonicalRepositoryCommand): void {
+  const isGitWorktreeAdd = (words: string[]) => {
+    const executable = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+    return executable === 'git' && words[1]?.toLowerCase() === 'worktree' && words[2]?.toLowerCase() === 'add';
+  };
+  if (command.kind === 'argv') {
+    if (isGitWorktreeAdd([command.executable!, ...(command.args ?? [])])) {
+      throw new Error('MANAGED_WORKSPACE_REQUIRED: repository_command_execute must not create an unmanaged temporary git worktree; use rh_work so Forge persists checkout/worktree ownership and terminal cleanup authority');
+    }
+    return;
+  }
+  for (const segment of shellSegments(command.shellCommand ?? '')) {
+    if (isGitWorktreeAdd(shellWords(segment))) {
+      throw new Error('MANAGED_WORKSPACE_REQUIRED: repository_command_execute must not create an unmanaged temporary git worktree; use rh_work so Forge persists checkout/worktree ownership and terminal cleanup authority');
+    }
+  }
+}
+
 export function assertRepositoryCommandInputAllowed(
   input: unknown,
   options: RepositoryCommandInputPolicyOptions = {},
 ): CanonicalRepositoryCommand {
   const command = assertRepositoryCommandStableHostIdentity(input);
+  assertNoUnmanagedControllerWorktreeLifecycle(command);
   if (command.kind === 'shell') {
     assertRepositoryCommandAllowed(command.shellCommand!, options);
   }
@@ -233,7 +275,70 @@ function readOnlyProgram(program: string | undefined): boolean {
   ].includes(program.toLowerCase()));
 }
 
+interface RepositoryCommandPathPolicyOptions {
+  controllerHome?: string;
+  repositoryId?: string;
+}
+
+interface SourceControllerRoundCompatibilityScope {
+  operation: 'round-close';
+  controllerHome: string;
+  workId: string;
+  controllerAuthorityId: string;
+  relayScopeId: string;
+}
+
+function sourceControllerRoundCompatibilityScope(
+  command: CanonicalRepositoryCommand,
+  options: RepositoryCommandPathPolicyOptions,
+): SourceControllerRoundCompatibilityScope | undefined {
+  if (command.kind !== 'argv' || !options.controllerHome || !options.repositoryId) return undefined;
+  const executable = command.executable?.split(/[\\/]/).at(-1)?.toLowerCase();
+  const args = command.args ?? [];
+  if (executable !== 'bun' || args[0] !== 'src/cli/index.ts' || args[1] !== 'chatgpt') return undefined;
+  const operation = args[2];
+  if (operation !== 'round-close') return undefined;
+
+  const allowedFlags = new Set(['--controller-home', '--repo-id', '--work-id', '--controller-authority-id', '--relay-scope-id', '--disposition', '--handoff-id', '--reason']);
+  const values = new Map<string, string>();
+  for (let index = 3; index < args.length; index += 2) {
+    const flag = args[index];
+    const value = args[index + 1];
+    if (!flag || !allowedFlags.has(flag) || !value || value.startsWith('--') || values.has(flag)) {
+      throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_CONTRACT_INVALID:${operation}:${flag ?? 'missing'}`);
+    }
+    values.set(flag, value);
+  }
+  const required = ['--controller-home', '--repo-id', '--work-id', '--controller-authority-id', '--relay-scope-id'];
+  for (const flag of required) {
+    if (!values.get(flag)?.trim()) throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_CONTRACT_INVALID:${operation}:${flag}`);
+  }
+  if (values.get('--repo-id') !== options.repositoryId) {
+    throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_REPOSITORY_MISMATCH:${values.get('--repo-id')}`);
+  }
+  const configuredControllerHome = realpathSync(options.controllerHome);
+  const requestedControllerHome = realpathSync(resolve(values.get('--controller-home')!));
+  if (requestedControllerHome !== configuredControllerHome) {
+    throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_CONTROLLER_HOME_MISMATCH:${requestedControllerHome}`);
+  }
+  const disposition = values.get('--disposition');
+  if (!disposition || !['wait', 'wait_for_user', 'goal_complete'].includes(disposition)) {
+    throw new Error(`SOURCE_CONTROLLER_ROUND_COMMAND_DISPOSITION_INVALID:${disposition ?? 'missing'}`);
+  }
+  if (disposition === 'wait_for_user' && !values.get('--handoff-id')?.trim()) {
+    throw new Error('SOURCE_CONTROLLER_ROUND_COMMAND_HANDOFF_REQUIRED');
+  }
+  return {
+    operation,
+    controllerHome: configuredControllerHome,
+    workId: values.get('--work-id')!,
+    controllerAuthorityId: values.get('--controller-authority-id')!,
+    relayScopeId: values.get('--relay-scope-id')!,
+  };
+}
+
 function grantCoversPath(grant: ExternalFilesystemGrant, canonicalPath: string, operation: RepositoryCommandExternalPathOperation): boolean {
+  if (operation === 'controller_local_effect') return false;
   if (externalFilesystemGrantExpired(grant)) return false;
   if (operation === 'external_read' && grant.mode !== 'read') return false;
   if (operation === 'external_copy_into_workspace' && grant.mode !== 'copy_into_repo') return false;
@@ -242,7 +347,7 @@ function grantCoversPath(grant: ExternalFilesystemGrant, canonicalPath: string,
 }
 
 function operationForToken(words: string[], index: number, external: string, cwd: string, root: string): RepositoryCommandExternalPathOperation | 'external_write' | 'unsupported' {
-  const program = words[0]?.toLowerCase();
+  const program = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
   if (!program) return 'unsupported';
   if (program === 'cp' || program === 'install') {
     const operands = words.slice(1).filter((word) => word && !word.startsWith('-'));
@@ -262,13 +367,27 @@ function operationForToken(words: string[], index: number, external: string, cwd
   return 'external_write';
 }
 
+function gitIndexOnlyRepositoryOperand(words: string[], index: number, candidateToken: string, cwd: string, root: string): boolean {
+  const executable = words[0]?.split(/[\\/]/).at(-1)?.toLowerCase();
+  if (executable !== 'git') return false;
+  const subcommand = words[1];
+  const indexOnly = subcommand === 'update-index'
+    || (subcommand === 'rm' && words.includes('--cached'))
+    || (subcommand === 'restore' && words.includes('--staged') && !words.includes('--worktree'));
+  if (!indexOnly || index < 2) return false;
+  const lexical = candidateToken.startsWith('/') ? resolve(candidateToken) : resolve(cwd, candidateToken);
+  return pathInside(root, lexical);
+}
+
 export function assertCommandPathOperandsStayInRepository(
   command: string | CanonicalRepositoryCommand,
   cwd: string,
   root: string,
   externalGrants: ExternalFilesystemGrant[] = [],
+  options: RepositoryCommandPathPolicyOptions = {},
 ): RepositoryCommandExternalPathUsage[] {
   const usages: RepositoryCommandExternalPathUsage[] = [];
+  const controllerRoundScope = typeof command === 'string' ? undefined : sourceControllerRoundCompatibilityScope(command, options);
   const segments = typeof command === 'string'
     ? shellSegments(command).map((segment) => ({ raw: segment, words: shellWords(segment) }))
     : command.kind === 'shell'
@@ -288,6 +407,10 @@ export function assertCommandPathOperandsStayInRepository(
       const absoluteInput = candidateToken.startsWith('/');
       if (!absoluteInput && !/[./\\*?]/.test(candidateToken) && !existsSync(join(cwd, candidateToken))) continue;
       const candidate = absoluteInput ? resolve(candidateToken) : resolve(cwd, candidateToken);
+      // Git index-only operations address the repository entry itself and do not
+      // dereference its symlink target. Fence them lexically to the repository;
+      // all filesystem-affecting operations still use realpath below.
+      if (gitIndexOnlyRepositoryOperand(words, index, candidateToken, cwd, root)) continue;
       const existing = nearestExistingPath(candidate);
       if (!existing) continue;
       const resolved = realpathSync(existing);
@@ -295,6 +418,18 @@ export function assertCommandPathOperandsStayInRepository(
       if (!absoluteInput) {
         throw new Error(`COMMAND_SCOPE_DENIED: command operand escapes repository root through a symlink or parent path: ${token}`);
       }
+      if (controllerRoundScope
+        && words[index - 1] === '--controller-home'
+        && resolved === controllerRoundScope.controllerHome) {
+        usages.push({
+          token,
+          canonicalPath: resolved,
+          operation: 'controller_local_effect',
+          grantKey: `tool-contract-abi:${controllerRoundScope.operation}:${controllerRoundScope.workId}`,
+          grantRoot: controllerRoundScope.controllerHome,
+        });
+        continue;
+      }
       if (sensitivePathDenied(resolved)) {
         throw new Error(`COMMAND_SCOPE_DENIED: sensitive external path is never allowed in repository commands: ${token}`);
       }