atris 3.82.1 → 3.82.3

package/lib/worktree-core.js

@@ -52,7 +52,8 @@ function runGit(args, { cwd = process.cwd(), check = true, timeout } = {}) {
   const network = ['fetch', 'push', 'ls-remote'].includes(args[0]);
   // Only network calls need the SSH probe; local calls skip its extra git spawn.
   const defaultTimeout = args[0] === 'push' ? GIT_PUSH_TIMEOUT_MS : network ? 30000 : undefined;
-  const options = { cwd, encoding: 'utf8', timeout: timeout ?? defaultTimeout,
+  // Listing a large repo's index or files can pass the 1 MB default buffer.
+  const options = { cwd, encoding: 'utf8', timeout: timeout ?? defaultTimeout, maxBuffer: COMMAND_MAX_BUFFER_BYTES,
     killSignal: 'SIGKILL', env: network ? gitNetworkEnvironment(process.env, cwd) : undefined };
   let result = spawnSync('git', args, options);
   // Linked checkouts share config. A concurrent start must not silently lose
@@ -1092,14 +1093,14 @@ function worktreeHasActiveProcess(worktreePath, activeCwds) {
   });
 }
 
-function recordWorktreeRemoval(root, { path: removedPath, branch = '', by, reason }) {
+function recordWorktreeRemoval(root, { path: removedPath, branch = '', by, reason, ...details }) {
   try {
     const common = runGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], { cwd: root, check: false });
     const main = common.status === 0 ? path.dirname(common.stdout.trim()) : root;
     const file = path.join(main, '.atris', 'state', 'worktree_removals.jsonl');
     fs.mkdirSync(path.dirname(file), { recursive: true });
     fs.appendFileSync(file, `${JSON.stringify({
-      at: new Date().toISOString(), path: removedPath, branch: branch || null, by, reason, pid: process.pid,
+      at: new Date().toISOString(), path: removedPath, branch: branch || null, by, reason, ...details, pid: process.pid,
     })}\n`);
   } catch {}
 }
@@ -1195,6 +1196,478 @@ function originBaseIsCurrent(root, base) {
     && match[2] === `refs/heads/${branch}` && local.stdout.trim() === match[1];
 }
 
+// The guarantee: a copy is removed only when every byte in it is proven saved
+// (committed and on origin) or proven throwaway. Anything unusual, or anything
+// the checks cannot read, keeps the copy for a person.
+//
+// Throwaway ignored folders are matched by exact place, never by name alone:
+// an install or cache folder right beside the package file that makes it
+// (package.json for node_modules, .next, .cache, .turbo; pyproject.toml,
+// setup.py or setup.cfg for the Python test caches). uploads/.cache/ and a
+// .cache/ with no package.json beside it are not throwaway.
+const JS_THROWAWAY_DIRS = new Set(['node_modules', '.next', '.cache', '.turbo']);
+const JS_PACKAGE_FILES = ['package.json'];
+const PY_THROWAWAY_DIRS = new Set(['.pytest_cache', '.mypy_cache', '.ruff_cache']);
+const PY_PACKAGE_FILES = ['pyproject.toml', 'setup.py', 'setup.cfg'];
+// Written by atris itself at the top of a copy: the start sidecar, prompt
+// files, watchdogs, its scratch and cache folders, and command usage counts.
+const ATRIS_PLUMBING_IGNORED = /^\.atris\/(?:agent-worktree\.json|fleet-prompt-[^/]+\.md|codex-watchdog\.js|codex-watchdog-[^/]+\.json|runtime-tmp\/.*|cache\/.*|state\/usage\.jsonl)$/;
+const THROWAWAY_IGNORED_FILE = /^(?:(?:.*\/)?\.DS_Store|tsconfig\.tsbuildinfo|next-env\.d\.ts)$/;
+const IGNORED_WALK_LIMIT = 20000;
+const RESCUE_IDLE_MS = 7 * DAY_MS;
+
+function throwawayIgnoredDir(wtPath, relative) {
+  const name = path.basename(relative);
+  const parent = path.dirname(relative);
+  // Even at the top of the copy, a cache counts only beside the package file that makes it.
+  const besidePackage = (files) => files.some((file) => {
+    try { return fs.lstatSync(path.join(wtPath, parent, file)).isFile(); } catch { return false; }
+  });
+  if (JS_THROWAWAY_DIRS.has(name)) return besidePackage(JS_PACKAGE_FILES);
+  if (PY_THROWAWAY_DIRS.has(name)) return besidePackage(PY_PACKAGE_FILES);
+  // Python bytecode folders sit beside every module; one counts only when it
+  // holds nothing but .pyc files.
+  if (name === '__pycache__') {
+    try {
+      return fs.readdirSync(path.join(wtPath, relative), { withFileTypes: true })
+        .every((entry) => entry.isFile() && entry.name.endsWith('.pyc'));
+    } catch { return false; }
+  }
+  return false;
+}
+
+function throwawayIgnoredFile(relative) {
+  return THROWAWAY_IGNORED_FILE.test(relative) || ATRIS_PLUMBING_IGNORED.test(relative);
+}
+
+// Ignored files in a copy that removal would lose: everything git ignores that
+// is not proven throwaway. null when the copy cannot be read or holds too many
+// files to check.
+function ignoredFilesToKeep(wtPath) {
+  const listed = runGit(['ls-files', '--others', '--ignored', '--exclude-standard', '--directory', '-z'], { cwd: wtPath, check: false });
+  if (listed.status !== 0 || listed.error) return null;
+  const keepers = [];
+  let walked = 0;
+  for (const entry of String(listed.stdout || '').split('\0').filter(Boolean)) {
+    const clean = entry.replace(/\/+$/, '');
+    if (!entry.endsWith('/')) {
+      if (!throwawayIgnoredFile(clean)) keepers.push(clean);
+      continue;
+    }
+    if (throwawayIgnoredDir(wtPath, clean)) continue;
+    const stack = [clean];
+    while (stack.length) {
+      const rel = stack.pop();
+      let children;
+      try { children = fs.readdirSync(path.join(wtPath, rel), { withFileTypes: true }); } catch { return null; }
+      for (const child of children) {
+        walked += 1;
+        if (walked > IGNORED_WALK_LIMIT) return null;
+        const childRel = `${rel}/${child.name}`;
+        if (child.isDirectory()) {
+          if (!throwawayIgnoredDir(wtPath, childRel)) stack.push(childRel);
+        } else if (!throwawayIgnoredFile(childRel)) {
+          keepers.push(childRel);
+        }
+      }
+    }
+  }
+  return keepers;
+}
+
+// Why a copy holds work the snapshot cannot prove it saved, or '' when it
+// holds none: index entries told to hide their edits, conflicts, sparse
+// checkouts, and nested repositories other than a registered submodule that
+// sits clean at a commit its own origin already has.
+function unprovableReason(wtPath) {
+  const flags = runGit(['ls-files', '-v', '-z'], { cwd: wtPath, check: false });
+  if (flags.status !== 0) return 'could not read the index';
+  const hidden = String(flags.stdout || '').split('\0').filter(Boolean)
+    .filter((row) => /^[a-zS]/.test(row)).map((row) => row.slice(2));
+  if (hidden.length) return `index entries hide their edits (assume-unchanged or skip-worktree): ${hidden.slice(0, 3).join(', ')}`;
+  const conflicts = runGit(['ls-files', '-u'], { cwd: wtPath, check: false });
+  if (conflicts.status !== 0 || String(conflicts.stdout || '').trim()) return 'unresolved merge conflicts';
+  const sparse = runGit(['config', '--bool', 'core.sparseCheckout'], { cwd: wtPath, check: false });
+  if (String(sparse.stdout || '').trim() === 'true') return 'sparse checkout';
+  // git lists an untracked folder that is its own repository as `name/`;
+  // committing it would save only a pointer, not its files or commits.
+  const untracked = runGit(['ls-files', '--others', '--exclude-standard', '-z'], { cwd: wtPath, check: false });
+  if (untracked.status !== 0) return 'could not list untracked files';
+  const nested = String(untracked.stdout || '').split('\0').filter((entry) => entry.endsWith('/'));
+  if (nested.length) return `nested git repository ${nested[0].replace(/\/$/, '')} is not saved by a commit`;
+  const listed = runGit(['ls-files', '-s', '-z'], { cwd: wtPath, check: false });
+  if (listed.status !== 0) return 'could not read the index';
+  const links = new Map();
+  for (const row of String(listed.stdout || '').split('\0').filter(Boolean)) {
+    const match = row.match(/^160000 ([0-9a-f]+) \d\t(.+)$/);
+    if (match) links.set(match[2], match[1]);
+  }
+  if (!links.size) return '';
+  const registered = runGit(['config', '--file', '.gitmodules', '--get-regexp', '^submodule\\..*\\.path$'], { cwd: wtPath, check: false });
+  const paths = new Set(String(registered.stdout || '').split('\n').map((line) => line.split(' ').slice(1).join(' ')).filter(Boolean));
+  for (const [link, oid] of links) {
+    if (!paths.has(link)) return `nested git repository ${link} is not a registered submodule`;
+    const dir = path.join(wtPath, link);
+    let entries = [];
+    try { entries = fs.readdirSync(dir); } catch {}
+    if (!entries.length) continue;
+    const head = runGit(['rev-parse', 'HEAD'], { cwd: dir, check: false });
+    const status = runGit(['status', '--porcelain', '--ignored=matching'], { cwd: dir, check: false });
+    const pushed = runGit(['branch', '-r', '--contains', oid], { cwd: dir, check: false });
+    if (head.status !== 0 || head.stdout.trim() !== oid || status.status !== 0 || String(status.stdout || '').trim()
+        || pushed.status !== 0 || !String(pushed.stdout || '').trim()) {
+      return `submodule ${link} has work not proven on its origin`;
+    }
+    // A clean status proves nothing if the submodule hides edits too.
+    const inner = unprovableReason(dir);
+    if (inner) return `submodule ${link}: ${inner}`;
+  }
+  return '';
+}
+
+// Settings that let git change bytes between disk and a commit. A content
+// filter (clean filters, LFS and the like) or the ident attribute (where
+// `$Id: any text $` hashes the same as `$Id$`) can hide local text even from
+// `git status`, so either keeps every copy, clean or dirty, on every removal
+// path. Line-ending and encoding conversion also keep a dirty copy, where the
+// rescue snapshot must match the disk byte for byte; on a clean copy they only
+// differ by reversible line endings or encoding, an accepted limit. A filter defined only in global config and named by no
+// attribute changes nothing and is allowed.
+const FILTER_ATTRIBUTE = /(?:^|\s)(?:filter|ident)(?:[=\s]|$)/m;
+const BYTE_CHANGING_ATTRIBUTE = /(?:^|\s)(?:filter|working-tree-encoding|eol|text|crlf|ident)(?:[=\s]|$)/m;
+
+function attributeFiles(wtPath) {
+  const files = [];
+  const listed = runGit(['ls-files', '--cached', '--others', '-z', '--', '.gitattributes', '*/.gitattributes'], { cwd: wtPath, check: false });
+  if (listed.status !== 0) return null;
+  for (const rel of String(listed.stdout || '').split('\0').filter(Boolean)) files.push(path.join(wtPath, rel));
+  const info = runGit(['rev-parse', '--path-format=absolute', '--git-path', 'info/attributes'], { cwd: wtPath, check: false });
+  if (info.status === 0 && info.stdout.trim()) files.push(info.stdout.trim());
+  const configured = runGit(['config', '--path', 'core.attributesFile'], { cwd: wtPath, check: false });
+  const fallback = path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'git', 'attributes');
+  files.push(configured.status === 0 && configured.stdout.trim() ? configured.stdout.trim() : fallback);
+  return files;
+}
+
+function byteChangingSetting(wtPath, { filtersOnly = false } = {}) {
+  const local = runGit(['config', '--local', '--get-regexp', '^filter\\.'], { cwd: wtPath, check: false });
+  if (String(local.stdout || '').trim()) return 'a content filter is set in this repo';
+  const worktreeScope = runGit(['config', '--worktree', '--get-regexp', '^filter\\.'], { cwd: wtPath, check: false });
+  if (String(worktreeScope.stdout || '').trim()) return 'a content filter is set in this copy';
+  for (const key of filtersOnly ? [] : ['core.autocrlf', 'core.eol']) {
+    const value = String(runGit(['config', key], { cwd: wtPath, check: false }).stdout || '').trim().toLowerCase();
+    if (value && value !== 'false' && !(key === 'core.eol' && value === 'native')) return `${key} converts line endings`;
+  }
+  const files = attributeFiles(wtPath);
+  if (!files) return 'could not list attribute files';
+  for (const file of files) {
+    let text = '';
+    try { text = fs.readFileSync(file, 'utf8'); } catch (error) {
+      if (error && error.code === 'ENOENT') continue;
+      return `could not read ${file}`;
+    }
+    const rows = text.split(/\r?\n/).filter((row) => !/^\s*(?:#|$)/.test(row));
+    const hit = rows.find((row) => (filtersOnly ? FILTER_ATTRIBUTE : BYTE_CHANGING_ATTRIBUTE).test(row));
+    if (hit) return `git attributes can change bytes on commit (${path.basename(file)}: ${hit.trim().slice(0, 60)})`;
+  }
+  return '';
+}
+
+function sizeKib(target) {
+  const measured = spawnSync('du', ['-sk', target], { encoding: 'utf8', timeout: 30000, killSignal: 'SIGKILL' });
+  const match = measured.status === 0 && !String(measured.stderr || '').trim() && String(measured.stdout || '').match(/^(\d+)\s/);
+  return match ? Number(match[1]) : 0;
+}
+
+function formatKib(kib) {
+  if (!Number.isFinite(kib) || kib <= 0) return 'an unknown amount';
+  if (kib >= 1024 * 1024) return `${(kib / (1024 * 1024)).toFixed(1)} GB`;
+  if (kib >= 1024) return `${Math.round(kib / 1024)} MB`;
+  return `${kib} KB`;
+}
+
+function worktreeEntry(root, wtPath) {
+  return listWorktrees(root).find((wt) => canonicalPath(wt.path) === canonicalPath(wtPath)) || null;
+}
+
+function remoteBranchOid(root, branch) {
+  const remote = runGit(['ls-remote', 'origin', `refs/heads/${branch}`], { cwd: root, check: false });
+  if (remote.status !== 0 || remote.error) return null;
+  const match = String(remote.stdout || '').match(/^([0-9a-f]{40,64})\s+refs\/heads\/(\S+)$/m);
+  return match && match[2] === branch ? match[1] : '';
+}
+
+// Where the copy's last commit is safe outside the copy: merged into the
+// branch it landed on, or sitting on the same branch at origin.
+function shippedWorkHome(root, { head, branch, landedOn }) {
+  if (landedOn) {
+    if (landedOn.startsWith('origin/')) refreshRemoteRef(root, landedOn);
+    if (runGit(['merge-base', '--is-ancestor', head, landedOn], { cwd: root, check: false }).status === 0) {
+      return baseBranchName(landedOn);
+    }
+  }
+  if (branch && remoteBranchOid(root, branch) === head) return `origin/${branch}`;
+  return '';
+}
+
+// Remove a copy right after ship lands or pushes it. Runs from the main
+// checkout, never from inside the copy. A copy with changes, files that cannot
+// come back, or another program inside it is kept and the reason returned.
+function removeShippedCopyNow({ root, primary, branch = '', landedOn = '', keep = false, env = process.env, atrisBin = ATRIS_BIN, activePaths = listActiveProcessPaths } = {}) {
+  if (keep) return { removed: false, reason: 'kept on request (--keep-copy)' };
+  if (env.ATRIS_WORKTREE_KEEP_AFTER_SHIP === '1') return { removed: false, reason: 'ATRIS_WORKTREE_KEEP_AFTER_SHIP=1' };
+  const copy = canonicalPath(root);
+  if (!primary || copy === canonicalPath(primary)) return { removed: false, reason: 'primary checkout', quiet: true };
+  if (!space.isAgentCopyPath(copy)) return { removed: false, reason: 'not an agent build copy', quiet: true };
+  if (space.isInside(atrisBin, copy)) return { removed: false, reason: 'this atris runs from inside the copy' };
+  const mainRoot = canonicalPath(primary);
+  const wt = worktreeEntry(mainRoot, copy);
+  if (!wt) return { removed: false, reason: 'not registered' };
+  if (wt.locked) return { removed: false, reason: 'locked' };
+  const counts = statusCounts(copy);
+  if (!counts) return { removed: false, reason: 'unreadable' };
+  if (counts.staged || counts.unstaged || counts.untracked) {
+    return { removed: false, reason: `it still has ${counts.staged + counts.unstaged + counts.untracked} unsaved changes` };
+  }
+  const keepers = ignoredFilesToKeep(copy);
+  if (!keepers) return { removed: false, reason: 'could not check the files git ignores', retry: true };
+  if (keepers.length) return { removed: false, reason: `it holds ignored files atris cannot rebuild: ${keepers.slice(0, 3).join(', ')}` };
+  const unprovable = byteChangingSetting(copy, { filtersOnly: true }) || unprovableReason(copy);
+  if (unprovable) return { removed: false, reason: unprovable };
+  const head = runGit(['rev-parse', 'HEAD'], { cwd: copy, check: false });
+  const headOid = head.status === 0 ? head.stdout.trim() : '';
+  if (!headOid) return { removed: false, reason: 'no commit' };
+  const home = shippedWorkHome(mainRoot, { head: headOid, branch, landedOn });
+  if (!home) return { removed: false, reason: 'could not confirm the work reached origin', retry: true };
+  // Step out first so this process is not one of the programs inside. The
+  // shell that ran ship still is, so a copy someone stands in waits for the
+  // delayed remover instead of vanishing under them.
+  if (space.isInside(process.cwd(), copy)) {
+    try { process.chdir(mainRoot); } catch { return { removed: false, reason: 'could not step out of the copy', retry: true }; }
+  }
+  const active = activePaths();
+  if (!Array.isArray(active)) return { removed: false, reason: 'could not list running programs', retry: true };
+  if (worktreeHasActiveProcess(copy, active)) return { removed: false, reason: 'a program is still working in it', retry: true };
+  const kib = sizeKib(copy);
+  const removed = runGit(['worktree', 'remove', copy], { cwd: mainRoot, check: false });
+  if (removed.status !== 0) return { removed: false, reason: `git refused: ${gitFailureDetail(removed) || 'remove failed'}`, retry: true };
+  recordWorktreeRemoval(mainRoot, { path: copy, branch, by: 'atris worktree ship', reason: 'shipped', saved_on: home, size_kib: kib });
+  return { removed: true, kib, home, path: copy };
+}
+
+// After a successful ship: remove the copy now, or hand a landed copy to the
+// delayed remover when something still runs inside it.
+function finishShippedCopy({ root, primary, branch, landedOn = '', keep = false, log = console.log, schedule = scheduleShippedCopyRemoval }) {
+  const result = removeShippedCopyNow({ root, primary, branch, landedOn, keep });
+  if (result.removed) {
+    log(`cleanup: removed this build copy and freed ${formatKib(result.kib)}; the work is safe on ${result.home}`);
+    return result;
+  }
+  if (result.retry && !keep) {
+    log(`cleanup: not yet (${result.reason})`);
+    announceShippedCopyRemoval(schedule({ root, primary, branch, base: landedOn }));
+    return result;
+  }
+  if (!result.quiet) log(`cleanup: kept this build copy (${result.reason})`);
+  return result;
+}
+
+// The delayed remover for a copy whose branch was pushed but not merged:
+// wait for quiet, then retry the same checks ship ran until the copy is free.
+function reapPushedCopy({
+  primary,
+  target,
+  branch = '',
+  settleMs = SHIP_SETTLE_MS,
+  pollMs = SHIP_REAP_POLL_MS,
+  giveUpMs = SHIP_REAP_GIVE_UP_MS,
+  sleep = sleepSync,
+  clock = Date.now,
+  remove = removeShippedCopyNow,
+} = {}) {
+  const startedAt = clock();
+  sleep(settleMs);
+  for (;;) {
+    const result = remove({ root: target, primary, branch });
+    if (result.removed) return { removed: true, reason: 'pushed' };
+    if (!result.retry || clock() - startedAt >= giveUpMs) return { removed: false, reason: result.reason };
+    sleep(pollMs);
+  }
+}
+
+// Snapshot a copy as two git trees through a throwaway copy of its index, so
+// the copy and its own index stay untouched: what is staged, and everything on
+// disk including untracked files. Keeping both means a staged version that
+// differs from the file on disk survives too.
+function snapshotTrees(wtPath) {
+  const realIndex = String(runGit(['rev-parse', '--path-format=absolute', '--git-path', 'index'], { cwd: wtPath, check: false }).stdout || '').trim();
+  const index = path.join(os.tmpdir(), `atris-rescue-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}.index`);
+  const env = { ...process.env, GIT_INDEX_FILE: index };
+  const run = (args) => spawnSync('git', args, { cwd: wtPath, encoding: 'utf8', env, maxBuffer: COMMAND_MAX_BUFFER_BYTES, timeout: 120000, killSignal: 'SIGKILL' });
+  try {
+    if (realIndex && fs.existsSync(realIndex)) fs.copyFileSync(realIndex, index);
+    else if (run(['read-tree', 'HEAD']).status !== 0) return null;
+    const staged = run(['write-tree']);
+    if (staged.status !== 0) return null;
+    if (run(['add', '-A']).status !== 0) return null;
+    const disk = run(['write-tree']);
+    if (disk.status !== 0) return null;
+    return { staged: staged.stdout.trim(), disk: disk.stdout.trim() };
+  } finally {
+    try { fs.rmSync(index, { force: true }); } catch {}
+  }
+}
+
+function newestChangeMs(wtPath) {
+  let newest = lastCopyActivityMs(wtPath);
+  const status = runGit(['status', '--porcelain=v1', '-z', '--untracked-files=all'], { cwd: wtPath, check: false });
+  if (status.status !== 0) return newest;
+  const fields = String(status.stdout || '').split('\0');
+  for (let i = 0; i < fields.length; i += 1) {
+    const row = fields[i];
+    if (row.length < 4) continue;
+    if (row[0] === 'R' || row[0] === 'C') i += 1;
+    try { newest = Math.max(newest, fs.lstatSync(path.join(wtPath, row.slice(3))).mtimeMs); } catch {}
+  }
+  return newest;
+}
+
+function commitIdentityEnv(wtPath) {
+  const email = runGit(['config', 'user.email'], { cwd: wtPath, check: false });
+  const name = runGit(['config', 'user.name'], { cwd: wtPath, check: false });
+  const env = { ...process.env };
+  if (email.status !== 0 || !email.stdout.trim()) {
+    env.GIT_AUTHOR_EMAIL = '299057014+atris-builder[bot]@users.noreply.github.com';
+    env.GIT_COMMITTER_EMAIL = env.GIT_AUTHOR_EMAIL;
+  }
+  if (name.status !== 0 || !name.stdout.trim()) {
+    env.GIT_AUTHOR_NAME = 'atris worktree sweep';
+    env.GIT_COMMITTER_NAME = env.GIT_AUTHOR_NAME;
+  }
+  return env;
+}
+
+// Rescue of abandoned dirty copies. Off unless the sweep runs with --rescue;
+// the timer never passes it, and the default sweep only reports these copies.
+//
+// Guarantee: a dirty copy is removed only when every byte in it is proven
+// saved on origin or proven throwaway. The staged and on-disk versions are
+// committed onto a brand-new atris-rescue/<copy>-<time> branch, created only
+// if the name is free here and on origin, pushed, confirmed on origin, and
+// the copy is checked again before removal. No existing branch ever moves.
+// Anything unusual keeps the copy for a person, with the reason.
+//
+// Accepted limits, each of which keeps the copy instead of risking it:
+// - ignored files other than installs and caches beside their package file,
+//   or atris's own plumbing
+// - nested repositories other than a submodule clean at a pushed commit
+// - index flags that hide edits, conflicts, sparse checkouts
+// - content filters and the ident attribute (on every removal path, clean
+//   copies too), and for dirty copies line-ending or encoding conversion
+// - a push the remote or its hooks refuse
+// What it cannot see: a program that writes into the copy between the last
+// check and the removal without holding a file open or standing in it.
+//
+// Returns { kept } with a reason, { candidate } on a dry run, or { removed }.
+function rescueAbandonedCopy({ root, wt, wtPath, item, counts, apply, now, idleMs, rescueIdleMs, rescue = false, activeCwdsOverride, budget, by }) {
+  const dirty = Boolean(counts && (counts.staged || counts.unstaged || counts.untracked));
+  const baseReason = dirty ? 'dirty' : (wt.branch === 'detached' ? 'detached_unmerged' : 'unmerged');
+  const keep = (reason, extra = {}) => ({ kept: { ...item, reason, ...(dirty ? { staged: counts.staged, unstaged: counts.unstaged, untracked: counts.untracked } : {}), ...extra } });
+  const named = Boolean(wt.branch && wt.branch !== 'detached');
+  if (runGit(['remote', 'get-url', 'origin'], { cwd: root, check: false }).status !== 0) return keep(baseReason, { rescue: 'no origin to push to' });
+  const keepers = ignoredFilesToKeep(wtPath);
+  if (!keepers) return keep('ignored_scan_failed');
+  if (keepers.length) return keep('ignored_data', { files: keepers.slice(0, 5) });
+  const unprovable = byteChangingSetting(wtPath, { filtersOnly: !dirty }) || unprovableReason(wtPath);
+  if (unprovable) return keep('unprovable', { why: unprovable });
+  const headOid = String(runGit(['rev-parse', 'HEAD'], { cwd: wtPath, check: false }).stdout || '').trim();
+  if (!headOid) return keep('missing_head');
+  const ownRemote = named ? remoteBranchOid(root, wt.branch) : '';
+  if (ownRemote === null) return keep(baseReason, { rescue: 'origin unreachable' });
+  const alreadySaved = !dirty && named && ownRemote === headOid;
+  const idleFor = now - newestChangeMs(wtPath);
+  const limit = alreadySaved ? idleMs : rescueIdleMs;
+  const idleDays = Math.round((idleFor / DAY_MS) * 10) / 10;
+  if (idleFor < limit) return keep(baseReason, { idle_days: idleDays });
+  // Without --rescue the sweep only reports a stale copy that needs saving.
+  if (!alreadySaved && !rescue) return keep(dirty ? 'stale_dirty' : 'stale_unpushed', { idle_days: idleDays, next: 'atris worktree sweep --rescue' });
+  const kib = sizeKib(wtPath);
+  if (!kib || budget.count >= 20 || budget.kib + kib > 10 * 1024 * 1024) return keep('size_unknown_or_cleanup_limit');
+  const fileCount = dirty ? counts.staged + counts.unstaged + counts.untracked : 0;
+  const rescueBranch = alreadySaved ? wt.branch
+    : `atris-rescue/${slugify(path.basename(wtPath), 'copy', 60)}-${stamp(new Date(now))}-${Math.random().toString(16).slice(2, 6)}`;
+  const candidate = {
+    ...item,
+    reason: alreadySaved ? 'pushed_branch' : 'rescued_to_branch',
+    rescue_branch: rescueBranch,
+    changed_files: fileCount,
+    idle_days: idleDays,
+    size_kib: kib,
+  };
+  budget.count += 1;
+  budget.kib += kib;
+  if (!apply) return { candidate };
+
+  const headTree = String(runGit(['rev-parse', 'HEAD^{tree}'], { cwd: wtPath, check: false }).stdout || '').trim();
+  const trees = dirty ? snapshotTrees(wtPath) : null;
+  if (dirty && !trees) return keep(baseReason, { rescue: 'could not snapshot the changes' });
+  let commit = headOid;
+  if (dirty) {
+    const trailer = 'Co-authored-by: Atris <299057014+atris-builder[bot]@users.noreply.github.com>';
+    const note = `The sweep found ${path.basename(wtPath)} idle for ${idleDays} days with changes nobody committed. It saved them here before removing the copy. Nothing was reviewed or merged.`;
+    const identity = commitIdentityEnv(wtPath);
+    const commitTree = (tree, parent, title) => {
+      const made = spawnSync('git', ['commit-tree', tree, '-p', parent, '-m', [title, '', note, '', trailer].join('\n')], {
+        cwd: wtPath, encoding: 'utf8', env: identity, timeout: 30000, killSignal: 'SIGKILL',
+      });
+      return made.status === 0 ? made.stdout.trim() : '';
+    };
+    // Staged work first, then what was on disk on top, so neither version is lost.
+    if (trees.staged !== headTree) {
+      commit = commitTree(trees.staged, commit, 'Rescue staged work from an abandoned build copy');
+      if (!commit) return keep(baseReason, { rescue: 'commit of the staged work failed' });
+    }
+    if (trees.disk !== trees.staged) {
+      commit = commitTree(trees.disk, commit, `Rescue unsaved work from an abandoned build copy (${fileCount} changed files)`);
+      if (!commit) return keep(baseReason, { rescue: 'commit of the work on disk failed' });
+    }
+  }
+  if (!alreadySaved) {
+    // Fresh name only: refuse if origin or this repo already has it.
+    const taken = remoteBranchOid(root, rescueBranch);
+    if (taken !== '') return keep('rescue_push_failed', { rescue_branch: rescueBranch, error: taken === null ? 'origin unreachable' : 'rescue branch name already on origin' });
+    const zero = '0'.repeat(commit.length);
+    const created = runGit(['update-ref', `refs/heads/${rescueBranch}`, commit, zero], { cwd: root, check: false });
+    if (created.status !== 0) return keep('rescue_push_failed', { rescue_branch: rescueBranch, error: `could not create the rescue branch: ${gitFailureDetail(created)}` });
+    const pushed = runGit(['push', 'origin', `refs/heads/${rescueBranch}:refs/heads/${rescueBranch}`], { cwd: root, check: false });
+    if (remoteBranchOid(root, rescueBranch) !== commit) {
+      return keep('rescue_push_failed', { rescue_branch: rescueBranch, rescue_commit: commit, error: (gitFailureDetail(pushed) || 'origin does not show the pushed commit').slice(0, 300) });
+    }
+  }
+  const freshActive = Array.isArray(activeCwdsOverride) ? activeCwdsOverride.map(canonicalPath) : listActiveProcessPaths();
+  const fresh = worktreeEntry(root, wtPath);
+  const freshHead = String(runGit(['rev-parse', 'HEAD'], { cwd: wtPath, check: false }).stdout || '').trim();
+  const freshTrees = dirty ? snapshotTrees(wtPath) : null;
+  const freshKeepers = ignoredFilesToKeep(wtPath);
+  const freshCounts = statusCounts(wtPath);
+  if (!Array.isArray(freshActive) || worktreeHasActiveProcess(wtPath, freshActive)
+      || !fresh || fresh.locked || freshHead !== headOid
+      || (dirty && (!freshTrees || freshTrees.staged !== trees.staged || freshTrees.disk !== trees.disk))
+      || !freshKeepers || freshKeepers.length || unprovableReason(wtPath) || byteChangingSetting(wtPath, { filtersOnly: !dirty }) || !freshCounts
+      || Boolean(freshCounts.staged || freshCounts.unstaged || freshCounts.untracked) !== dirty) {
+    return keep('changed_or_active_during_verification', { rescue_branch: rescueBranch, rescue_commit: commit });
+  }
+  const removeArgs = dirty ? ['worktree', 'remove', '--force', wtPath] : ['worktree', 'remove', wtPath];
+  const removed = runGit(removeArgs, { cwd: root, check: false });
+  if (removed.status !== 0) {
+    return keep('remove_failed', { rescue_branch: rescueBranch, rescue_commit: commit, error: gitFailureDetail(removed) });
+  }
+  const originUrl = String(runGit(['remote', 'get-url', 'origin'], { cwd: root, check: false }).stdout || '').trim();
+  const rescueRecord = { branch: rescueBranch, commit, remote: originUrl, copy_branch: named ? wt.branch : null, changed_files: fileCount };
+  recordWorktreeRemoval(root, { path: wt.path, branch: wt.branch, by, reason: candidate.reason, rescue: rescueRecord, size_kib: kib });
+  return { removed: { ...candidate, rescue_commit: commit } };
+}
+
 function cleanupWorktrees({
   root = repoRoot(),
   base: baseOverride = '',
@@ -1207,6 +1680,8 @@ function cleanupWorktrees({
   freshGraceMs = WORKTREE_REAP_GRACE_MS,
   now = Date.now(),
   cleanupBudget = null,
+  rescueIdleMs = 0,
+  rescue = false,
 } = {}) {
   const worktrees = listWorktrees(root);
   const primary = worktrees[0]?.path ? path.resolve(worktrees[0].path) : '';
@@ -1219,6 +1694,8 @@ function cleanupWorktrees({
   const removed = [];
   const cacheCandidates = [];
   const cachePruned = [];
+  const rescued = [];
+  const rescueCandidates = [];
   const cacheBudget = cleanupBudget || { count: 0, kib: 0 };
   const scopePaths = Array.isArray(onlyPaths) ? onlyPaths.map(canonicalPath) : null;
   const inScope = (wtPath) => (!scopePaths || scopePaths.includes(canonicalPath(wtPath)))
@@ -1264,19 +1741,44 @@ function cleanupWorktrees({
       kept.push({ ...item, reason: 'missing_or_unreadable' });
       continue;
     }
+    const tryRescue = (dirtyCounts) => {
+      const outcome = rescueAbandonedCopy({
+        root, wt, wtPath, item, counts: dirtyCounts, apply, now, idleMs, rescueIdleMs, rescue, activeCwdsOverride, budget: cacheBudget, by,
+      });
+      if (outcome.removed) {
+        removed.push(outcome.removed);
+        rescued.push(outcome.removed);
+      } else if (outcome.candidate) {
+        candidates.push(outcome.candidate);
+        rescueCandidates.push(outcome.candidate);
+      } else {
+        if (outcome.kept.reason !== 'changed_or_active_during_verification') pruneCachesForKept(wtPath);
+        kept.push(outcome.kept);
+      }
+    };
     if (counts.staged || counts.unstaged || counts.untracked) {
+      if (rescueIdleMs > 0) {
+        tryRescue(counts);
+        continue;
+      }
       pruneCachesForKept(wtPath);
       kept.push({ ...item, reason: 'dirty', staged: counts.staged, unstaged: counts.unstaged, untracked: counts.untracked });
       continue;
     }
-    const ignored = runGit(['ls-files', '--others', '--ignored', '--exclude-standard', '--directory', '-z'], { cwd: wt.path, check: false });
-    if (ignored.status !== 0 || ignored.error) {
+    const keepers = ignoredFilesToKeep(wt.path);
+    if (!keepers) {
       kept.push({ ...item, reason: 'ignored_scan_failed' });
       continue;
     }
-    if (ignored.stdout) {
+    if (keepers.length) {
       pruneCachesForKept(wtPath);
-      kept.push({ ...item, reason: 'ignored_data' });
+      kept.push({ ...item, reason: 'ignored_data', files: keepers.slice(0, 5) });
+      continue;
+    }
+    const unprovable = byteChangingSetting(wt.path, { filtersOnly: true }) || unprovableReason(wt.path);
+    if (unprovable) {
+      pruneCachesForKept(wtPath);
+      kept.push({ ...item, reason: 'unprovable', why: unprovable });
       continue;
     }
     if (!wt.head) {
@@ -1289,6 +1791,10 @@ function cleanupWorktrees({
       continue;
     }
     const merged = runGit(['merge-base', '--is-ancestor', wt.head, base], { cwd: root, check: false }).status === 0;
+    if (!merged && rescueIdleMs > 0) {
+      tryRescue(null);
+      continue;
+    }
     if (!merged) {
       pruneCachesForKept(wtPath);
       kept.push({ ...item, reason: wt.branch === 'detached' ? 'detached_unmerged' : 'unmerged' });
@@ -1326,14 +1832,14 @@ function cleanupWorktrees({
     if (!apply) continue;
     const freshActive = Array.isArray(activeCwdsOverride) ? activeCwds : listActiveProcessPaths();
     const freshCounts = statusCounts(wt.path);
-    const freshIgnored = runGit(['ls-files', '--others', '--ignored', '--exclude-standard', '--directory', '-z'], { cwd: wt.path, check: false });
+    const freshKeepers = ignoredFilesToKeep(wt.path);
     const freshSize = spawnSync('du', ['-sk', wtPath], { encoding: 'utf8', timeout: 30000, killSignal: 'SIGKILL' });
     const freshMatch = freshSize.status === 0 && !String(freshSize.stderr || '').trim() && String(freshSize.stdout || '').match(/^(\d+)\s/);
     const gitdir = runGit(['rev-parse', '--absolute-git-dir'], { cwd: wtPath, check: false });
     const freshHead = runGit(['rev-parse', 'HEAD'], { cwd: wtPath, check: false });
     if (!Array.isArray(freshActive) || worktreeHasActiveProcess(wtPath, freshActive)
         || !freshCounts || freshCounts.staged || freshCounts.unstaged || freshCounts.untracked
-        || freshIgnored.status !== 0 || freshIgnored.stdout || !freshMatch || Number(freshMatch[1]) !== kib
+        || !freshKeepers || freshKeepers.length || unprovableReason(wt.path) || byteChangingSetting(wt.path, { filtersOnly: true }) || !freshMatch || Number(freshMatch[1]) !== kib
         || gitdir.status !== 0 || !gitdir.stdout.trim() || fs.existsSync(path.join(gitdir.stdout.trim(), 'locked'))
         || freshHead.status !== 0 || String(freshHead.stdout || '').trim() !== wt.head
         || runGit(['merge-base', '--is-ancestor', wt.head, base], { cwd: root, check: false }).status !== 0
@@ -1351,17 +1857,17 @@ function cleanupWorktrees({
     }
   }
 
-  return { apply, base, candidates, removed, kept, cacheCandidates, cachePruned };
+  return { apply, base, candidates, removed, kept, cacheCandidates, cachePruned, rescued, rescueCandidates };
 }
 
 const SWEEP_IDLE_MS = 2 * 60 * 60 * 1000;
 const SWEEP_EVERY_HOURS = 3;
 const SWEEP_HIDDEN_KEPT = new Set(['primary_checkout', 'current_checkout', 'out_of_scope']);
 
-function sweepWorkspace({ workspace, apply = false, idleMs = SWEEP_IDLE_MS, activeCwds, freeSpace = space.freeBytes, by = 'atris worktree sweep', cleanupBudget = null } = {}) {
+function sweepWorkspace({ workspace, apply = false, idleMs = SWEEP_IDLE_MS, rescueIdleMs = RESCUE_IDLE_MS, rescue = false, activeCwds, freeSpace = space.freeBytes, by = 'atris worktree sweep', cleanupBudget = null } = {}) {
   const root = path.resolve(workspace);
   const before = freeSpace(root);
-  const report = { workspace: root, apply, idle_ms: idleMs, before, after: before, repos: [] };
+  const report = { workspace: root, apply, rescue, idle_ms: idleMs, rescue_idle_ms: rescueIdleMs, before, after: before, repos: [] };
   const scan = Array.isArray(activeCwds) ? activeCwds.map(canonicalPath) : listActiveProcessPaths();
   if (!Array.isArray(scan)) return { ...report, error: 'could not list running programs, so every copy was kept' };
   const scope = path.join(root, space.AGENT_COPIES_DIR);
@@ -1375,12 +1881,14 @@ function sweepWorkspace({ workspace, apply = false, idleMs = SWEEP_IDLE_MS, acti
         continue;
       }
       const shared = Array.isArray(activeCwds) || !apply ? scan : undefined;
-      const result = cleanupWorktrees({ root: repo.root, base, apply, activeCwds: shared, by, onlyUnder: scope, idleMs, cleanupBudget });
+      const result = cleanupWorktrees({ root: repo.root, base, apply, activeCwds: shared, by, onlyUnder: scope, idleMs, rescueIdleMs, rescue, cleanupBudget });
       report.repos.push({
         ...entry,
         base: result.base,
         removed: result.removed,
         candidates: result.candidates,
+        rescued: result.rescued,
+        rescueCandidates: result.rescueCandidates,
         cachePruned: result.cachePruned,
         cacheCandidates: result.cacheCandidates,
         kept: result.kept.filter((item) => !SWEEP_HIDDEN_KEPT.has(item.reason)),
@@ -1400,7 +1908,7 @@ const SWEEP_KEPT_LABELS = {
   dirty: 'with changes',
   unmerged: 'not merged',
   detached_unmerged: 'not merged',
-  ignored_data: 'holding files git ignores (kept for review)',
+  ignored_data: 'holding ignored files that cannot be rebuilt (kept for review)',
   ignored_scan_failed: 'unreadable',
   fresh_worktree_grace: 'new',
   recent_activity: 'used recently',
@@ -1414,6 +1922,10 @@ const SWEEP_KEPT_LABELS = {
   path_not_canonical: 'behind a link',
   size_unknown_or_cleanup_limit: 'over the per-run limit',
   changed_or_active_during_verification: 'changed during the check',
+  rescue_push_failed: 'push of its saved work failed',
+  unprovable: 'holding work atris cannot prove it saved',
+  stale_dirty: 'stale with unsaved changes (save with --rescue)',
+  stale_unpushed: 'stale with commits not on origin (save with --rescue)',
 };
 
 function plural(count, one, many) {
@@ -1448,10 +1960,13 @@ function sweepSchedulePlan({ workspace, everyHours = SWEEP_EVERY_HOURS, homeDir
 
 module.exports = {
   ATRIS_BIN,
+  reapPushedCopy,
+  RESCUE_IDLE_MS,
+  finishShippedCopy,
+  formatKib,
   SWEEP_IDLE_MS,
   SWEEP_EVERY_HOURS,
   SWEEP_KEPT_LABELS,
-  announceShippedCopyRemoval,
   assertOneLapProofTree,
   baseBranchName,
   branchName,