Function recoverOrphanedSandbox

src/agent/git-sandbox.ts:429–473

(
  repoRoot: string,
  signal?: AbortSignal,
)

 * Not wired into the loop here (out of scope); exported for the caller to use.
 */
export async function recoverOrphanedSandbox(
  repoRoot: string,
  signal?: AbortSignal,
): Promise<OrphanedSandbox | null> {
  try {
    if (!(await isGitRepo(repoRoot, signal))) return null;

    // 1. The persisted recovery record, if any.
    let record: SandboxRecoveryRecord | null = null;
    try {
      const raw = await fs.readFile(recoveryRecordPath(repoRoot), 'utf-8');
      const parsed = JSON.parse(raw);
      if (parsed && parsed.version === 1 && typeof parsed.branch === 'string') {
        record = parsed as SandboxRecoveryRecord;
      }
    } catch {
      /* no record (clean shutdown) or unreadable — fall through to git scan */
    }

    // 2. Leftover sandbox branches.
    const br = await git(['branch', '--list', 'qodex/sandbox-*', '--format=%(refname:short)'], { cwd: repoRoot, signal });
    const branches = br.exitCode === 0
      ? br.stdout.split('\n').map((s) => s.trim()).filter(Boolean)
      : [];

    // 3. Leftover WIP stashes from a killed sandbox.
    const sl = await git(['stash', 'list', '--format=%gd %gs'], { cwd: repoRoot, signal });
    const stashes = sl.exitCode === 0
      ? sl.stdout.split('\n')
          .map((l) => l.trim())
          .filter((l) => l.includes('qodex-sandbox-wip-'))
          .map((l) => {
            const sp = l.split(/\s+/);
            return { ref: sp[0] ?? '', message: l.slice((sp[0] ?? '').length).trim() };
          })
          .filter((s) => s.ref)
      : [];

    if (!record && branches.length === 0 && stashes.length === 0) return null;
    return { record, branches, stashes };
  } catch (e: any) {
    logger.debug('recoverOrphanedSandbox failed', { err: e?.message });
    return null;
  }
}