Method begin

src/agent/git-sandbox.ts:140–217

* Enter the sandbox. Returns true if isolation is now active, false if it * couldn't be set up (non-git, detached HEAD, etc.) — in which case the caller * proceeds without isolation.

(taskId: string, signal?: AbortSignal)

   * proceeds without isolation.
   */
  async begin(taskId: string, signal?: AbortSignal): Promise<boolean> {
    let lock: LockHandle | null = null;
    try {
      if (!(await isGitRepo(this.cwd, signal))) {
        logger.debug('GitSandbox: not a git repo — running without isolation');
        return false;
      }
      const repoRoot = await repoToplevel(this.cwd, signal);
      if (!repoRoot) {
        logger.debug('GitSandbox: could not resolve repo root — skipping isolation');
        return false;
      }

      // Advisory repo lock: stop two sessions in one repo interleaving HEAD/stash
      // mutations. A short retry budget means a LIVE holder makes us decline (run
      // without isolation) rather than block; a dead holder's stale lock is
      // reclaimed by acquireLock's staleMs path. The lock dir must exist first.
      const lockPath = sandboxLockPath(repoRoot);
      await fs.mkdir(path.dirname(lockPath), { recursive: true }).catch(() => {});
      try {
        lock = await acquireLock(lockPath, { retries: 3, intervalMs: 150, staleMs: 30_000 });
      } catch {
        logger.info('GitSandbox: another session holds the sandbox lock — running without isolation');
        return false;
      }

      const origin = await this.currentBranch(signal);
      if (!origin) {
        logger.debug('GitSandbox: detached HEAD — skipping isolation');
        await lock.release();
        return false;
      }
      const base = await this.headSha(signal);
      if (!base) { await lock.release(); return false; }

      // Stash any uncommitted work so the sandbox starts from a clean tree and
      // the user's WIP is preserved untouched. The message is unique per task so
      // finish() can restore THIS stash by message, never another session's.
      const status = await git(['status', '--porcelain'], { cwd: this.cwd, signal });
      const dirty = (status.exitCode === 0) && status.stdout.trim().length > 0;
      const stashMessage = `qodex-sandbox-wip-${taskId}`;
      let stashed = false;
      if (dirty) {
        const s = await git(['stash', 'push', '-u', '-m', stashMessage], { cwd: this.cwd, signal });
        stashed = (s.exitCode === 0);
        if (!(s.exitCode === 0)) {
          logger.debug('GitSandbox: stash failed — skipping isolation to avoid touching dirty tree');
          await lock.release();
          return false;
        }
      }

      const branch = `qodex/sandbox-${taskId}`;
      const co = await git(['checkout', '-b', branch], { cwd: this.cwd, signal });
      if (!(co.exitCode === 0)) {
        // Roll back the stash if we made one, then bail.
        if (stashed) await this.restoreStashByMessage(stashMessage, signal);
        logger.debug('GitSandbox: branch create failed — no isolation', { err: co.stderr });