@moretea-labs/forge 1.5.1 → 1.7.0

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

@@ -0,0 +1,108 @@
+import { spawn, type ChildProcess } from 'child_process';
+import { capProcessOutput, redactProcessOutput } from '../../effects/process-runner';
+import { repositoryChildProcessEnvironment } from '../../runtime/shared/process-environment';
+import { terminateProcessTree } from '../../runtime/shared/process-tree';
+import type { CanonicalRepositoryCommand } from './command-normalization';
+
+export interface SpawnCommandResult {
+  ok: boolean;
+  exitCode: number;
+  timedOut: boolean;
+  cancelled: boolean;
+  stdout: string;
+  stderr: string;
+}
+export interface RepositoryCommandAsyncHooks {
+  onSpawn?: (pid: number) => void;
+  onStdout?: (chunk: string) => void;
+  onStderr?: (chunk: string) => void;
+  /** Observe the exact child exit result before repository post-processing begins. */
+  onExit?: (result: SpawnCommandResult) => void;
+  signal?: AbortSignal;
+}
+
+export function commandEnvironment(): NodeJS.ProcessEnv {
+  const allowed = ['PATH', 'HOME', 'USER', 'LOGNAME', 'TMPDIR', 'TMP', 'TEMP', 'SHELL', 'LANG', 'LC_ALL', 'TERM', 'SSH_AUTH_SOCK', 'GPG_TTY', 'XDG_CONFIG_HOME'];
+  const env: NodeJS.ProcessEnv = {};
+  for (const key of allowed) if (process.env[key] !== undefined) env[key] = process.env[key];
+  env.GIT_TERMINAL_PROMPT = '0';
+  env.CI = '1';
+  return repositoryChildProcessEnvironment(env);
+}
+
+export function collectOutput(maxOutputBytes: number): { write(chunk: string | Buffer): void; complete(): string } {
+  const chunks: Buffer[] = [];
+  let totalBytes = 0;
+  let truncated = false;
+  return {
+    write(chunk) {
+      const buffer = typeof chunk === 'string' ? Buffer.from(chunk, 'utf8') : chunk;
+      if (buffer.length === 0) return;
+      if (totalBytes >= maxOutputBytes) { truncated = true; return; }
+      const remaining = maxOutputBytes - totalBytes;
+      chunks.push(buffer.length <= remaining ? buffer : buffer.subarray(0, remaining));
+      totalBytes += Math.min(buffer.length, remaining);
+      if (buffer.length > remaining) truncated = true;
+    },
+    complete() {
+      const redacted = redactProcessOutput(Buffer.concat(chunks).toString('utf8'));
+      return truncated ? capProcessOutput(redacted, maxOutputBytes) : redacted;
+    },
+  };
+}
+
+async function killCommandTree(child: ChildProcess): Promise<void> {
+  const pid = child.pid;
+  if (!pid) return;
+  try {
+    if (process.platform !== 'win32') {
+      try { process.kill(-pid, 'SIGTERM'); } catch { child.kill('SIGTERM'); }
+    } else child.kill();
+  } catch { /* already exited */ }
+  await terminateProcessTree(pid, { gracePeriodMs: 200, killAfterMs: 1_000, pollIntervalMs: 25 });
+}
+
+export async function runCanonicalCommand(
+  command: CanonicalRepositoryCommand,
+  cwd: string,
+  timeoutMs: number,
+  maxOutputBytes: number,
+  hooks: RepositoryCommandAsyncHooks = {},
+): Promise<SpawnCommandResult> {
+  if (hooks.signal?.aborted) return { ok: false, exitCode: 1, timedOut: false, cancelled: true, stdout: '', stderr: 'cancelled before spawn' };
+  const executable = command.kind === 'argv' ? command.executable! : process.platform === 'win32' ? 'cmd.exe' : '/bin/sh';
+  const args = command.kind === 'argv' ? [...(command.args ?? [])] : process.platform === 'win32' ? ['/d', '/s', '/c', command.shellCommand!] : ['-c', command.shellCommand!];
+  const display = typeof command.value === 'string' ? command.value : JSON.stringify(command.value);
+  const stdout = collectOutput(maxOutputBytes);
+  const stderr = collectOutput(maxOutputBytes);
+  return await new Promise<SpawnCommandResult>((resolve) => {
+    const child = spawn(executable, args, { cwd, env: commandEnvironment(), stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+    if (child.pid) hooks.onSpawn?.(child.pid);
+    let settled = false;
+    let timedOut = false;
+    let cancelled = false;
+    let spawnError = '';
+    let timeoutHandle: NodeJS.Timeout | undefined;
+    const finish = (exitCode: number) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutHandle) clearTimeout(timeoutHandle);
+      hooks.signal?.removeEventListener('abort', onAbort);
+      const errors = [stderr.complete()];
+      if (timedOut) errors.push(`process timed out after ${timeoutMs}ms: ${redactProcessOutput(display)}`);
+      if (cancelled) errors.push('process cancelled');
+      if (spawnError) errors.push(redactProcessOutput(spawnError));
+      const result = { ok: exitCode === 0 && !timedOut && !cancelled && !spawnError, exitCode, timedOut, cancelled, stdout: stdout.complete(), stderr: capProcessOutput(errors.filter(Boolean).join('\n'), maxOutputBytes) };
+      try { hooks.onExit?.(result); } catch { /* observation hooks must never change the command outcome */ }
+      resolve(result);
+    };
+    const onAbort = () => { cancelled = true; void killCommandTree(child).finally(() => finish(1)); };
+    timeoutHandle = setTimeout(() => { timedOut = true; void killCommandTree(child).finally(() => finish(1)); }, timeoutMs);
+    timeoutHandle.unref();
+    hooks.signal?.addEventListener('abort', onAbort, { once: true });
+    child.stdout?.on('data', (chunk) => { stdout.write(chunk); hooks.onStdout?.(chunk.toString()); });
+    child.stderr?.on('data', (chunk) => { stderr.write(chunk); hooks.onStderr?.(chunk.toString()); });
+    child.on('error', (error) => { spawnError = error.message; });
+    child.on('close', (code) => finish(code ?? 1));
+  });
+}

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

@@ -50,64 +50,122 @@ export function resolveRepositoryCommandCwd(
   return { root, cwd, relativeCwd };
 }
 
-export function assertRepositoryCommandAllowed(command: string): string {
+interface RepositoryCommandInputPolicyOptions {
+  /** Internal lane hint: preserve repository policy while allowing an already-classified local script shape. */
+  allowOpaqueLocalScript?: boolean;
+}
+
+export function assertRepositoryCommandAllowed(
+  command: string,
+  _options: RepositoryCommandInputPolicyOptions = {},
+): string {
   const normalized = command.trim();
   if (!normalized) throw new Error('COMMAND_INVALID: command is required');
   if (normalized.length > MAX_COMMAND_LENGTH) {
     throw new Error(`COMMAND_INVALID: command exceeds ${MAX_COMMAND_LENGTH} characters`);
   }
   if (normalized.includes('\0')) throw new Error('COMMAND_INVALID: command contains a null byte');
-
-  const denied: Array<[RegExp, string]> = [
-    [/\$\(|`/, 'nested command substitution is not allowed'],
-    [/(?:^|[;&|]\s*)(?:eval|source)\b|(?:^|[;&|]\s*)\.\s+[^/]/i, 'dynamic shell evaluation is not allowed'],
-    [/\b(?:bash|sh|zsh|fish|dash|cmd|powershell|pwsh)\b\s+(?:-[^\s]*c\b|\/c\b)/i, 'nested shell execution is not allowed'],
-    [/\b(?:python\d*|node|ruby|perl)\b\s+(?:-[ce]\b|--eval\b)/i, 'inline interpreter execution is not allowed'],
-    [/(?:^|[\s'"=])(?:\.\.(?:\/|\\)|~(?:\/|\\)|[A-Za-z]:[\\/])/, 'ambiguous parent/home/drive paths are not allowed; use repo-relative paths or an authorized absolute external path'],
-    [/(?:^|[;&|]\s*)cd(?:\s|$)/i, 'use the cwd argument instead of cd'],
-    [/\b(?:env|printenv)\b|\bgh\s+auth\s+token\b|\bgit\s+credential\b|\bsecurity\s+find-(?:generic|internet)-password\b/i, 'credential or environment inspection is not allowed'],
-    [/(?:^|[\s'"/])(?:\.ssh|\.aws|\.gnupg|Library\/Keychains|login\.keychain|\.config\/gh\/hosts\.yml)(?:[\s'"/]|$)/i, 'sensitive credential paths are not allowed'],
-    [/(?:^|[;&|]\s*)(?:curl|wget|scp|sftp|ftp|nc|ncat|netcat|socat|ssh)(?:\s|$)/i, 'direct network or exfiltration utilities are not allowed'],
-    [/\bgit\s+(?:--git-dir|--work-tree|-C)\b|\b(?:GIT_DIR|GIT_WORK_TREE)\s*=/i, 'Git repository scope overrides are not allowed'],
-    [/\bgit\s+config\b[^\n]*(?:--global|--system)\b/i, 'global or system Git configuration changes are not allowed'],
-  ];
-  for (const [pattern, reason] of denied) {
-    if (pattern.test(normalized)) throw new Error(`COMMAND_POLICY_DENIED: ${reason}`);
-  }
+  // Repository commands are an execution surface, not a shell-language policy
+  // engine. Do not maintain an enumerated command/program denylist here: it is
+  // necessarily incomplete and turns new CLI/subcommand shapes into false
+  // negatives. Structural repository/cwd/external-path authority is enforced
+  // separately after normalization.
   return normalized;
 }
 
-export function assertRepositoryCommandInputAllowed(input: unknown): CanonicalRepositoryCommand {
-  const command = normalizeRepositoryCommand(input);
+function macOsTccSensitiveShellTool(command: string): string | undefined {
+  const match = command.match(/(?:^|[\n;&|])\s*(?:[A-Za-z_][A-Za-z0-9_]*=[^\s]+\s+)*(?:(?:command|exec|sudo|nohup)\s+)?(?:\/usr\/(?:bin|sbin)\/)?(osascript|screencapture)(?=\s|$)/i);
+  return match?.[1]?.toLowerCase();
+}
+
+function macOsTccSensitiveArgvTool(command: CanonicalRepositoryCommand): string | undefined {
+  if (command.kind !== 'argv') return undefined;
+  const executableName = command.executable!.split(/[\\/]/).at(-1)?.toLowerCase() ?? '';
+  if (executableName === 'osascript' || executableName === 'screencapture') return executableName;
+  if (!['bash', 'sh', 'zsh', 'fish', 'dash', 'cmd', 'powershell', 'pwsh'].includes(executableName)) return undefined;
+  const args = command.args ?? [];
+  const commandFlagIndex = args.findIndex((arg) => /^(?:-[^-]*c[^-]*|\/c|-Command)$/i.test(arg));
+  if (commandFlagIndex < 0) return undefined;
+  const shellPayload = args[commandFlagIndex + 1];
+  return typeof shellPayload === 'string' ? macOsTccSensitiveShellTool(shellPayload) : undefined;
+}
+
+const INLINE_INTERPRETERS = new Set(['node', 'nodejs', 'bun', 'deno']);
+const SHELL_INTERPRETERS = new Set(['bash', 'sh', 'zsh', 'fish', 'dash']);
+const FORGE_PLUGIN_ACTION_EXECUTOR = /\b(?:submitAssistantPluginAction|executeAssistantPluginAction|executeBrowserPluginAction)\b/;
+const FORGE_RUNTIME_PLUGIN_IMPORT = /(?:\bfrom\s*|\bimport\s*\(|\brequire\s*\()\s*['"][^'"]*(?:^|[\\/])(?:src[\\/])?runtime[\\/]plugins[\\/][^'"]+['"]/m;
+
+function inlineEvalPayload(command: CanonicalRepositoryCommand): string | undefined {
   if (command.kind === 'shell') {
-    assertRepositoryCommandAllowed(command.shellCommand!);
-    return command;
+    const shell = command.shellCommand ?? '';
+    return /(?:^|[;&|]\s*|\s)(?:node|nodejs|bun|deno)(?:\s+[^\n;&|]*)?\s(?:-e|--eval)(?:\s|=)/i.test(shell)
+      ? shell
+      : undefined;
   }
   const executableName = command.executable!.split(/[\\/]/).at(-1)?.toLowerCase() ?? '';
   const args = command.args ?? [];
-  const shellFlag = args.some((arg) => ['-c', '/c', '-Command'].includes(arg));
-  if (['bash', 'sh', 'zsh', 'fish', 'dash', 'cmd', 'powershell', 'pwsh'].includes(executableName) && shellFlag) {
-    throw new Error('COMMAND_POLICY_DENIED: nested shell execution is not allowed');
-  }
-  if (['node', 'nodejs', 'bun', 'deno', 'ruby', 'perl', 'python', 'python3'].includes(executableName)
-    && args.some((arg) => ['-c', '-e', '--eval'].includes(arg))) {
-    throw new Error('COMMAND_POLICY_DENIED: inline interpreter execution is not allowed');
+  if (SHELL_INTERPRETERS.has(executableName)) {
+    const commandFlagIndex = args.findIndex((arg) => /^(?:-[^-]*c[^-]*)$/i.test(arg));
+    const payload = commandFlagIndex >= 0 ? args[commandFlagIndex + 1] : undefined;
+    return typeof payload === 'string'
+      && /(?:^|[;&|]\s*|\s)(?:node|nodejs|bun|deno)(?:\s+[^\n;&|]*)?\s(?:-e|--eval)(?:\s|=)/i.test(payload)
+      ? payload
+      : undefined;
   }
-  if (args.some((arg) => /(?:^|[\\/])\.\.(?:[\\/]|$)|^(?:~|[A-Za-z]:[\\/])/.test(arg))) {
-    throw new Error('COMMAND_POLICY_DENIED: ambiguous parent/home/drive paths are not allowed; use repo-relative paths or an authorized absolute external path');
-  }
-  if (args.some((arg) => /(?:^|[\\/])(?:\.ssh|\.aws|\.gnupg|Library[\\/]Keychains|login\.keychain|\.config[\\/]gh[\\/]hosts\.yml)(?:[\\/]|$)/i.test(arg))) {
-    throw new Error('COMMAND_POLICY_DENIED: sensitive credential paths are not allowed');
-  }
-  if (executableName === 'git' && args.some((arg) => ['--git-dir', '--work-tree', '-C'].includes(arg))) {
-    throw new Error('COMMAND_POLICY_DENIED: Git repository scope overrides are not allowed');
+  if (!INLINE_INTERPRETERS.has(executableName)) return undefined;
+  const evalIndex = args.findIndex((arg) => arg === '-e' || arg === '--eval');
+  if (evalIndex >= 0) return args[evalIndex + 1];
+  const inline = args.find((arg) => arg.startsWith('--eval='));
+  return inline?.slice('--eval='.length);
+}
+
+/**
+ * Process Runtime deliberately supports bounded direct argv eval for diagnostics
+ * and test helpers. What it must not support is using that escape hatch as a
+ * second plugin executor: typed plugin actions own authorization, resource
+ * claims, receipts, and recovery semantics through plugin_action_execute.
+ */
+export function assertRepositoryCommandNoPluginExecutionBypass(input: unknown): CanonicalRepositoryCommand {
+  const command = normalizeRepositoryCommand(input);
+  const payload = inlineEvalPayload(command);
+  if (payload && FORGE_PLUGIN_ACTION_EXECUTOR.test(payload) && FORGE_RUNTIME_PLUGIN_IMPORT.test(payload)) {
+    throw new Error(
+      'PLUGIN_ACTION_EXECUTION_REQUIRES_TYPED_PLUGIN_TOOL: repository commands may not invoke Forge runtime plugin action internals; use plugin_action_execute so typed authorization, resource claims, receipts, and recovery remain authoritative',
+    );
   }
-  if (executableName === 'git' && args[0] === 'config' && args.some((arg) => ['--global', '--system'].includes(arg))) {
-    throw new Error('COMMAND_POLICY_DENIED: global or system Git configuration changes are not allowed');
+  return command;
+}
+
+/**
+ * Runtime releases live at release-specific executable paths. Never let those
+ * binaries become macOS TCC principals: GUI automation and screen capture must
+ * be owned by the stable Forge Desktop Operator / typed browser provider.
+ */
+export function assertRepositoryCommandStableHostIdentity(input: unknown): CanonicalRepositoryCommand {
+  const command = normalizeRepositoryCommand(input);
+  const tool = command.kind === 'shell'
+    ? macOsTccSensitiveShellTool(command.shellCommand!)
+    : macOsTccSensitiveArgvTool(command);
+  if (tool) {
+    throw new Error(
+      `COMMAND_POLICY_DENIED: ${tool} is macOS TCC-sensitive and must run through the stable Forge Desktop Operator/browser capability; forge-runtime must not become the permission identity`,
+    );
   }
-  if (['env', 'printenv', 'curl', 'wget', 'scp', 'sftp', 'ftp', 'nc', 'ncat', 'netcat', 'socat', 'ssh'].includes(executableName)) {
-    throw new Error('COMMAND_POLICY_DENIED: credential or network inspection is not allowed');
+  return command;
+}
+
+export function assertRepositoryCommandInputAllowed(
+  input: unknown,
+  options: RepositoryCommandInputPolicyOptions = {},
+): CanonicalRepositoryCommand {
+  const command = assertRepositoryCommandStableHostIdentity(input);
+  if (command.kind === 'shell') {
+    assertRepositoryCommandAllowed(command.shellCommand!, options);
   }
+  // Do not infer execution permission from executable names, shell flags, inline
+  // interpreter flags, network utilities, or Git subcommands. Those rules are
+  // not complete enough to be an authority boundary. Real repository and
+  // external-filesystem scope is validated by assertCommandPathOperandsStayInRepository.
   return command;
 }
 

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

@@ -12,20 +12,19 @@ export function resolveControllerHome(explicit?: string): string {
 }
 
 /**
- * Prefer env, then repo-local self-host layout (`_ops/controller-home`) used by
- * `forge runtime service install`, then the user-global default.
+ * Resolve the one installed Controller Home. A repository containing a retired
+ * `_ops/controller-home` is evidence for an explicit migration only; its mere
+ * presence must never redirect a package Runtime, CLI, or MCP caller away from
+ * the user-level authority.
+ *
+ * Repo-local storage remains available only through an explicit
+ * `--controller-home` argument or `FORGE_CONTROLLER_HOME` configuration.
  */
 export function resolveRepoPreferredControllerHome(repoRoot?: string, explicit?: string): string {
   const trimmedExplicit = explicit?.trim();
   if (trimmedExplicit) return resolveControllerHome(trimmedExplicit);
   const configured = process.env.FORGE_CONTROLLER_HOME?.trim();
   if (configured) return resolveControllerHome(configured);
-  if (repoRoot?.trim()) {
-    const opsHome = join(resolve(repoRoot.trim()), '_ops', 'controller-home');
-    if (existsSync(join(opsHome, 'mcp', 'mcp.local.json')) || existsSync(opsHome)) {
-      return resolve(opsHome);
-    }
-  }
   return resolveControllerHome();
 }
 

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

@@ -9,6 +9,7 @@ import { resolveRepositoryCommandCwd } from './command-scope';
 import type { RepositoryRecord } from './types';
 import { assertResolvedAuthorization, decideAuthorization, type AuthorizationDecision } from '../../runtime/control-plane/governance/authorization';
 import { readRepositoryAccessPolicy } from '../../runtime/control-plane/governance/access-policy';
+import { invalidateRepositoryReadCaches } from '../repository/inspector';
 
 export interface ExecuteRepositoryGitCommandInput {
   args: string[];
@@ -296,6 +297,7 @@ export function executeRepositoryGitCommand(
     after,
     repositoryChanged: snapshotChanged(before, after),
   };
+  if (execution.repositoryChanged) invalidateRepositoryReadCaches(root);
   auditExecution(controllerHome, repository, execution);
   return execution;
 }

package/src/cli/repositories/locks.ts

@@ -1,4 +1,4 @@
-import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from 'fs';
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from 'fs';
 import { dirname, join } from 'path';
 import { ensureControllerHome, repositoryControllerRoot } from './controller-home';
 import { recordGatewayLatency } from '../../runtime/observability/gateway-contention-metrics';
@@ -39,7 +39,6 @@ export type ControllerLockTryResult =
 const DEFAULT_ASYNC_LOCK_WAIT_MS = 500;
 const MAX_ASYNC_LOCK_WAIT_MS = 5_000;
 const LOCK_POLL_INTERVAL_MS = 10;
-const CORRUPT_LOCK_GRACE_MS = 1_000;
 
 function safe(value: string): string {
   return value.replace(/[^a-zA-Z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'unknown';
@@ -96,23 +95,59 @@ function isPidAlive(pid: number | undefined): boolean {
   }
 }
 
-export function readControllerLock(controllerHome: string, key: ControllerLockKey): ControllerLockRecord | undefined {
+function readControllerLockRecord(path: string): ControllerLockRecord | undefined {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as ControllerLockRecord;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Reap only the exact stale lock identity that the caller observed. The
+ * per-lockId guard serializes competing reapers, then the canonical path is
+ * re-read before unlink so an owner that replaced the stale record is never
+ * deleted from an old observation.
+ */
+export function reapControllerLockIfUnchanged(
+  controllerHome: string,
+  key: ControllerLockKey,
+  observed: ControllerLockRecord,
+): boolean {
   const path = controllerLockPath(controllerHome, key);
+  const guardPath = `${path}.reap-${safe(observed.lockId)}.guard`;
+  let guardFd: number | undefined;
   try {
-    const record = JSON.parse(readFileSync(path, 'utf-8')) as ControllerLockRecord;
-    if (isExpired(record) || !isPidAlive(record.pid)) {
-      rmSync(path, { force: true });
-      return undefined;
-    }
-    return record;
+    guardFd = openSync(guardPath, 'wx');
   } catch {
-    try {
-      if (Date.now() - statSync(path).mtimeMs >= CORRUPT_LOCK_GRACE_MS) rmSync(path, { force: true });
-    } catch {
-      /* a concurrent owner may still be creating or releasing the lock */
-    }
+    return false;
+  }
+  try {
+    const current = readControllerLockRecord(path);
+    if (!current || current.lockId !== observed.lockId) return false;
+    if (!isExpired(current) && isPidAlive(current.pid)) return false;
+    rmSync(path, { force: true });
+    return true;
+  } finally {
+    if (guardFd !== undefined) closeSync(guardFd);
+    rmSync(guardPath, { force: true });
+  }
+}
+
+export function readControllerLock(controllerHome: string, key: ControllerLockKey): ControllerLockRecord | undefined {
+  const path = controllerLockPath(controllerHome, key);
+  const record = readControllerLockRecord(path);
+  if (!record) {
+    // Canonical lock publication is atomic. A malformed file therefore means
+    // legacy/corrupt state; fail closed instead of deleting an identity that
+    // cannot be compared safely.
+    return undefined;
+  }
+  if (isExpired(record) || !isPidAlive(record.pid)) {
+    reapControllerLockIfUnchanged(controllerHome, key, record);
     return undefined;
   }
+  return record;
 }
 
 function metric(key: ControllerLockKey, waitedMs: number, outcome: 'success' | 'contention' | 'timeout'): void {
@@ -157,9 +192,11 @@ export function tryAcquireControllerLock(
   };
   let fd: number | undefined;
   try {
+    // The exclusive create is the ownership primitive. A concurrent reader may
+    // briefly observe incomplete JSON, but malformed state is never deleted;
+    // competing open(..., 'wx') attempts therefore still fail closed.
     fd = openSync(path, 'wx');
-    writeFileSync(fd, `${JSON.stringify(record, null, 2)}
-`, 'utf-8');
+    writeFileSync(fd, `${JSON.stringify(record, null, 2)}\n`, 'utf-8');
     const waitedMs = performance.now() - started;
     if (recordMetrics) metric(key, waitedMs, 'success');
     return { acquired: true, lock: record, waitedMs };

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

@@ -0,0 +1,121 @@
+import { createHash } from 'crypto';
+import { existsSync, lstatSync, readFileSync, readlinkSync } from 'fs';
+import { resolve } from 'path';
+import { spawn, spawnSync } from 'child_process';
+import { capProcessOutput, redactProcessOutput } from '../../effects/process-runner';
+import { commandEnvironment, collectOutput } from './command-process';
+
+export interface RepositoryCommandSnapshot {
+  head: string | null;
+  branch: string | null;
+  status: string;
+  dirty: boolean;
+  refsHash: string;
+  paths: string[];
+  pathFingerprints: Record<string, string>;
+}
+
+export function emptyWorkspaceSnapshot(): RepositoryCommandSnapshot {
+  return { head: null, branch: null, status: '', dirty: false, refsHash: createHash('sha256').update('').digest('hex'), paths: [], pathFingerprints: {} };
+}
+
+function commandOutput(command: string, args: string[], cwd: string, maxOutputBytes: number): { ok: boolean; stdout: string } {
+  const result = spawnSync(command, args, { cwd, env: commandEnvironment(), encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'], timeout: 10_000, maxBuffer: Math.max(maxOutputBytes, 1024 * 1024) });
+  return { ok: result.status === 0 && !result.error, stdout: capProcessOutput(redactProcessOutput(typeof result.stdout === 'string' ? result.stdout : ''), maxOutputBytes) };
+}
+function gitText(root: string, args: string[]): string {
+  const output = commandOutput('git', ['-C', root, ...args], root, 256 * 1024);
+  return output.ok ? output.stdout.trim() : '';
+}
+const SNAPSHOT_PATHS = ['.', ':(exclude).ai/harness/**', ':(exclude)_ops/controller-home/**'];
+function statusPath(line: string): string | undefined {
+  if (!line.trim() || line.startsWith('##')) return undefined;
+  const raw = line.length > 3 ? line.slice(3) : '';
+  const path = raw.includes(' -> ') ? raw.split(' -> ').at(-1) : raw;
+  return path?.replace(/^"|"$/g, '');
+}
+function pathFingerprint(root: string, relativePath: string, statusLines: string[]): string {
+  const hash = createHash('sha256').update(statusLines.join('\n'));
+  const absolute = resolve(root, relativePath);
+  if (!existsSync(absolute)) return hash.update('\nmissing').digest('hex');
+  try {
+    const stat = lstatSync(absolute);
+    if (stat.isSymbolicLink()) hash.update(`\nsymlink:${readlinkSync(absolute)}`);
+    else if (stat.isFile()) hash.update('\nfile:').update(readFileSync(absolute));
+    else hash.update(`\nmode:${stat.mode}:size:${stat.size}`);
+  } catch (error) { hash.update(`\nunreadable:${error instanceof Error ? error.message : String(error)}`); }
+  return hash.digest('hex');
+}
+function buildSnapshot(root: string, head: string | null, branch: string | null, status: string, refs: string): RepositoryCommandSnapshot {
+  const lines = status.split(/\r?\n/).filter((line) => line && !line.startsWith('##'));
+  const byPath = new Map<string, string[]>();
+  for (const line of lines) {
+    const path = statusPath(line); if (!path) continue;
+    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) ?? [])])) };
+}
+
+export function repositorySnapshot(root: string): RepositoryCommandSnapshot {
+  return buildSnapshot(root, gitText(root, ['rev-parse', '--verify', 'HEAD']) || null, gitText(root, ['branch', '--show-current']) || null, gitText(root, ['status', '--porcelain=v1', '--branch', '--untracked-files=all', '--', ...SNAPSHOT_PATHS]), gitText(root, ['show-ref']));
+}
+
+interface GitResult { ok: boolean; exitCode: number; stdout: string; stderr: string; timedOut: boolean; cancelled: boolean }
+async function gitAsync(root: string, args: string[], signal?: AbortSignal): Promise<GitResult> {
+  if (signal?.aborted) return { ok: false, exitCode: 1, stdout: '', stderr: 'cancelled', timedOut: false, cancelled: true };
+  return await new Promise((resolveResult) => {
+    const child = spawn('git', ['-C', root, ...args], { cwd: root, env: commandEnvironment(), stdio: ['ignore', 'pipe', 'pipe'], detached: process.platform !== 'win32' });
+    const stdout = collectOutput(256 * 1024); const stderr = collectOutput(64 * 1024);
+    let settled = false; let timedOut = false; let cancelled = false;
+    const finish = (exitCode: number, forcedError?: string) => {
+      if (settled) return; settled = true; clearTimeout(timeout); signal?.removeEventListener('abort', abort);
+      resolveResult({ ok: exitCode === 0 && !timedOut && !cancelled, exitCode, stdout: stdout.complete().trim(), stderr: forcedError ?? stderr.complete(), timedOut, cancelled });
+    };
+    const timeout = setTimeout(() => { timedOut = true; try { child.kill(); } catch {} finish(1, `git ${args.join(' ')} timed out`); }, 10_000); timeout.unref();
+    const abort = () => { cancelled = true; try { child.kill(); } catch {} finish(1, 'cancelled'); };
+    signal?.addEventListener('abort', abort, { once: true });
+    child.stdout?.on('data', (chunk) => stdout.write(chunk)); child.stderr?.on('data', (chunk) => stderr.write(chunk));
+    child.on('error', (error) => finish(1, error.message)); child.on('close', (code) => finish(code ?? 1));
+  });
+}
+
+const MAX_DIRTY_PATHS = 200;
+export async function repositorySnapshotAsync(
+  root: string,
+  signal?: AbortSignal,
+  options: { pathFingerprints?: boolean } = {},
+): Promise<RepositoryCommandSnapshot> {
+  const [headResult, branchResult, statusResult, refsResult] = await Promise.all([
+    gitAsync(root, ['rev-parse', '--verify', 'HEAD'], signal), gitAsync(root, ['branch', '--show-current'], signal),
+    gitAsync(root, ['status', '--porcelain=v1', '--branch', '--untracked-files=all', '--', ...SNAPSHOT_PATHS], signal), gitAsync(root, ['show-ref'], signal),
+  ]);
+  if ([headResult, branchResult, statusResult, refsResult].some((result) => result.cancelled)) throw new Error('CANCELLED: repository snapshot aborted');
+  if (statusResult.timedOut || headResult.timedOut) throw new Error('SNAPSHOT_TIMEOUT: git snapshot timed out');
+  if (!statusResult.ok) throw new Error(`SNAPSHOT_FAILED: git status exit ${statusResult.exitCode}: ${statusResult.stderr}`);
+  let head: string | null = null;
+  if (headResult.ok) head = headResult.stdout || null;
+  else if (!(headResult.exitCode === 128 || /unknown revision|bad revision|Needed a single revision|ambiguous argument|not a valid object name/i.test(headResult.stderr))) throw new Error(`SNAPSHOT_FAILED: git rev-parse HEAD exit ${headResult.exitCode}: ${headResult.stderr}`);
+  const refs = refsResult.ok || (refsResult.exitCode === 1 && (!refsResult.stderr.trim() || /expected|no match|no references/i.test(refsResult.stderr))) ? refsResult.stdout || '' : (() => { throw new Error(`SNAPSHOT_FAILED: git show-ref exit ${refsResult.exitCode}: ${refsResult.stderr}`); })();
+  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();
+  let pathFingerprints: Record<string, string> = {};
+  if (includePathFingerprints) {
+    const { computePathFingerprintsAsync } = await import('../../runtime/execution/thin-harness/fingerprint-worker');
+    const fingerprint = await computePathFingerprintsAsync({ root, paths, statusByPath: Object.fromEntries(byPath), maxFileBytes: 256 * 1024, maxTotalBytes: 8 * 1024 * 1024, maxPaths: MAX_DIRTY_PATHS }, { signal, timeoutMs: 5_000 });
+    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 };
+}
+
+export function changedSnapshotPaths(before: RepositoryCommandSnapshot, after: RepositoryCommandSnapshot): string[] {
+  return [...new Set([...before.paths, ...after.paths])].filter((path) => before.pathFingerprints[path] !== after.pathFingerprints[path]).sort();
+}
+export function snapshotChanged(before: RepositoryCommandSnapshot, after: RepositoryCommandSnapshot): boolean {
+  return before.head !== after.head || before.branch !== after.branch || before.refsHash !== after.refsHash || changedSnapshotPaths(before, after).length > 0;
+}

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

@@ -7,6 +7,7 @@ import {
   getEditSession,
   type EditOperation,
   type EditSession,
+  type EditSessionBinding,
   type EditSessionPatchError,
 } from '../editing/edit-session';
 import { getMcpPolicy } from '../mcp/policy';
@@ -345,6 +346,7 @@ export function applySafePatch(repository: RepositoryRecord, input: {
   continueOnError?: unknown;
   refreshFingerprints?: unknown;
   recoverStaleSession?: unknown;
+  binding?: EditSessionBinding;
 }): SafePatchApplyResult {
   const operations = normalizedSafePatchOperations(input.operations);
   if (operations.length === 0) throw new Error('SAFE_PATCH_OPERATIONS_REQUIRED: provide at least one operation');
@@ -356,7 +358,7 @@ export function applySafePatch(repository: RepositoryRecord, input: {
   const allowedPaths = Array.isArray(input.allowedPaths) ? input.allowedPaths.map((item) => String(item).trim()).filter(Boolean) : undefined;
   let session = sessionId
     ? getEditSession(repository.canonicalRoot, sessionId)
-    : beginEditSession(repository.canonicalRoot, { purpose: String(input.purpose ?? 'Safe repository patch').trim() || 'Safe repository patch', allowedPaths });
+    : beginEditSession(repository.canonicalRoot, { purpose: String(input.purpose ?? 'Safe repository patch').trim() || 'Safe repository patch', allowedPaths, binding: input.binding });
   const createdSession = !sessionId;
   let recoveredSession: SafePatchRecoveredSession | undefined;
   const appliedChunks: SafePatchAppliedChunk[] = [];
@@ -376,17 +378,17 @@ export function applySafePatch(repository: RepositoryRecord, input: {
       continue;
     }
     try {
-      session = applyEditOperations(repository.canonicalRoot, policy, session.sessionId, preflight.operations.map(stripInternalIndex), { expectedRevision, maxBatchOperations: MAX_SAFE_PATCH_CHUNK_SIZE });
+      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')) {
         const previousSessionId = session.sessionId;
-        session = beginEditSession(repository.canonicalRoot, { purpose: `${String(input.purpose ?? 'Safe repository patch').trim() || 'Safe repository patch'} (recovered)`, allowedPaths });
+        session = beginEditSession(repository.canonicalRoot, { purpose: `${String(input.purpose ?? 'Safe repository patch').trim() || 'Safe repository patch'} (recovered)`, allowedPaths, binding: input.binding });
         expectedRevision = session.currentRevision;
         recoveredSession = { reason: 'Previous edit session fingerprints were stale; remaining chunks were moved into a fresh session.', 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 });
+          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;

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 { withControllerLock } from './locks';
 import type { RepositoryRecord } from './types';
 
 const DEFAULT_MAX_OUTPUT_BYTES = 128 * 1024;
@@ -254,6 +255,11 @@ export function commitSelectedPaths(
   const message = String(input.message ?? '').trim();
   if (!message) throw new Error('COMMIT_MESSAGE_REQUIRED: message is required');
 
+  return withControllerLock(
+    controllerHome,
+    { scope: 'worktree', repoId: repository.repoId, worktreeId: repository.activeCheckoutId },
+    `selected-path-commit:${repository.activeCheckoutId}`,
+    () => {
   const stage = executeRepositoryGitCommand(controllerHome, repository, {
     args: ['add', '--all', '--', ...paths],
     authorization: 'explicit_user_request',
@@ -281,15 +287,17 @@ export function commitSelectedPaths(
     args: ['commit', '--only', '-m', message, '--', ...paths],
     authorization: 'explicit_user_request',
   });
-  return {
-    paths,
-    stage,
-    stagedPaths: staged,
-    commit,
-    ...(commit.status !== 'executed' || commit.ok !== true
-      ? { error: { code: 'SELECTED_PATH_COMMIT_FAILED', message: commit.stderr || 'git commit failed for selected paths' } }
-      : {}),
-  };
+      return {
+        paths,
+        stage,
+        stagedPaths: staged,
+        commit,
+        ...(commit.status !== 'executed' || commit.ok !== true
+          ? { error: { code: 'SELECTED_PATH_COMMIT_FAILED', message: commit.stderr || 'git commit failed for selected paths' } }
+          : {}),
+      };
+    },
+  );
 }
 
 export function prepareTransferArtifacts(