agentbox-app 0.1.12 → 0.1.13

package/main/task-folders.mjs

@@ -34,12 +34,36 @@
 //   the lock carries the owning pid and a release from anyone else checks
 //   whether that process is still alive.
 //
+// WHICH MEANS THE FOLDER HAS AN OWNER, AND TAKING IT IS AN ANSWER (2026-10-07).
+// It used to be a side effect that could not fail: `lock` only wrote a lock
+// when there was none, so the folder a restarted app picked up still named the
+// pid of the app that had exited, and anybody reading that lock found a dead
+// owner and was free to delete the folder a live agent was standing in. A live
+// FOREIGN lock did not stop reuse either, so two app processes over one
+// checkout — one from the app folder, one from a checkout, which happens here
+// daily — both got the same folder and both were told it was theirs.
+//
+// So `acquireTaskFolder` answers: taken, or refused and by whom. Taking over a
+// lock whose owner is gone is a deliberate step that WRITES the new owner. A
+// lock somebody put on by hand carries no pid of ours and is nobody's to take.
+// The half-built copy at `.building-<id>` carries the same ownership, so one
+// app's build is never swept away by the other's.
+//
+// AND THE FOLDER IS THE COMMIT PLUS WHAT THE REPOSITORY ASKED FOR (2026-10-07,
+// w-5952e6de3e). A worktree holds tracked content and nothing else, so every
+// file a repository needs and git does not track was missing: measured that day,
+// five of the seven task folders then live had no `zero.config.json`, the app's
+// own config, and ran on fallback defaults. The list of local files to carry is
+// `.worktreeinclude` at the repository root, read by `main/worktree-include.mjs`,
+// which is the same file Conductor and Claude Code read for the same purpose.
+//
 // Branches are never deleted here. Every commit survives the folder, so the
 // worst this can do is make somebody run `git worktree add` again.
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { nameSlug } from '../shared/product-name.mjs';
+import { carryLocalFiles, copyTree, onlyTrackedContent, trackedTopLevel } from './worktree-include.mjs';
 
 /** Where Claude Code puts its own, so both engines and a human agree. */
 const WORKTREES = ['.claude', 'worktrees'];
@@ -57,15 +81,27 @@ const git = (cwd, args) => execFileSync('git', args, {
   cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
 }).trim();
 
+/**
+ * What is in a directory. One we cannot even read is reported as holding
+ * something, because the only decision taken on this answer is whether the
+ * directory is safe to delete, and "we could not look" is not a yes.
+ */
+function tryRead(dir) {
+  try { return fs.readdirSync(dir); } catch { return ['we could not look']; }
+}
+
 /** Git that answers rather than throws, for the questions where "no" is fine. */
 function tryGit(cwd, args) {
   try { return { ok: true, out: git(cwd, args) }; }
   catch (error) { return { ok: false, out: String(error?.stderr ?? error?.message ?? '').trim() }; }
 }
 
+/** `safeTaskName`'s question, asked of a folder already on the disk without throwing. */
+const couldBeATaskName = (name) => SAFE_NAME.test(name) && String(name).length <= 64;
+
 export function safeTaskName(id) {
   const name = String(id ?? '');
-  if (!SAFE_NAME.test(name) || name.length > 64) {
+  if (!couldBeATaskName(name)) {
     throw Error(`Not a name a task folder may be given: ${JSON.stringify(id)}`);
   }
   return name;
@@ -161,8 +197,74 @@ function registered(repoPath) {
 const record = (repoPath, folder) => registered(repoPath).find((w) => w.path === folder) ?? null;
 
 /**
- * The folder this task works in, made if it is not there yet. those
- * sessions keep running exactly where they ran before.
+ * WHO HOLDS THIS FOLDER, which is the one question every answer here is built
+ * on. Four answers and they are not the same shape:
+ *
+ *   no lock at all           free, and whoever asks may write their own
+ *   our own pid              already ours
+ *   a lock with no pid of    SOMEBODY ELSE'S, for good: a person who ran
+ *   ours in it               `git worktree lock` meant it, and there is no
+ *                            process to find dead
+ *   another pid, alive       theirs while it lives
+ *   another pid, gone        free, but only through a takeover that writes
+ *                            the new owner (`stale`)
+ */
+function holder(root, folder, pid) {
+  const held = record(root, folder)?.lock;
+  if (held === undefined) return { ok: true, heldBy: null, free: true };
+  const owner = pidInReason(held);
+  if (owner === pid) return { ok: true, heldBy: pid };
+  if (owner === null) return { ok: false, reason: 'locked', heldBy: null };
+  if (alive(owner)) return { ok: false, reason: 'held', heldBy: owner };
+  return { ok: true, heldBy: owner, stale: true };
+}
+
+/**
+ * TAKE THE FOLDER, OR SAY WHO HAS IT. Never a side effect: the caller gets
+ * `taken` either way, and a refusal names the process in the way.
+ *
+ * A takeover writes the new owner, because the pid in that lock is the whole
+ * of the protection `releaseTaskFolder` and `parkTaskFolder` have. It is read
+ * back afterwards rather than assumed: `git worktree unlock` and `lock` are two
+ * commands, so two processes taking over the same dead owner's folder at the
+ * same moment is possible, and the one that did not end up in the lock has to
+ * hear that it did not get the folder.
+ */
+export function acquireTaskFolder(root, folder, { pid = process.pid } = {}) {
+  const held = holder(root, folder, pid);
+  if (!held.ok) return { taken: false, reason: held.reason, heldBy: held.heldBy };
+  if (!held.free && !held.stale) return { taken: true, heldBy: pid };
+
+  if (held.stale) tryGit(root, ['worktree', 'unlock', folder]);
+  tryGit(root, ['worktree', 'lock', '--reason', lockReason(pid), folder]);
+
+  const after = record(root, folder)?.lock;
+  const now = pidInReason(after);
+  if (now === pid) return { taken: true, heldBy: pid };
+  if (after === undefined) return { taken: false, reason: 'refused', heldBy: null };
+  return { taken: false, reason: now ? 'held' : 'locked', heldBy: now ?? null };
+}
+
+/**
+ * The folder this task works in, TAKEN by this process, and made if it is not
+ * there yet. Either `{ taken: true, path, branch, created, heldBy }`, or
+ * `{ taken: false, reason, heldBy, path: null }` when somebody else has it:
+ *
+ *   held         another live process is working in it
+ *   building     another live process is part way through making it
+ *   locked       a person locked it by hand, so it is not ours to take
+ *   in-the-way   something that is not a task folder sits at that path
+ *
+ * `path: null` on every refusal, because there is no folder the asker may work
+ * in and a caller reaching for `.path` should get nothing rather than the
+ * folder somebody else is standing in.
+ *
+ * `how` SAYS WHICH OF THE TWO WAYS MADE IT: `clone` for the block-sharing copy,
+ * `checkout` for the ordinary one, `kept` for a folder that was already there.
+ * It is reported because the two ways are not equally good and a test that only
+ * checks the RESULT cannot tell them apart: the clone could break for good and
+ * every assertion about the folder's contents would still pass. Codex made that
+ * point reviewing this file on 2026-10-07 and it was right.
  */
 export function ensureTaskFolder(dir, id, { pid = process.pid, dependencies = true } = {}) {
   const name = safeTaskName(id);
@@ -170,10 +272,29 @@ export function ensureTaskFolder(dir, id, { pid = process.pid, dependencies = tr
   if (!root) return null;
   const folder = taskFolderPath(root, name);
   const branch = taskBranch(name);
+  const refused = (held) => ({ taken: false, reason: held.reason, heldBy: held.heldBy ?? null, path: null });
 
   if (fs.existsSync(folder) && record(root, folder)) {
-    lock(root, folder, pid);
-    return { path: folder, branch: record(root, folder)?.branch ?? branch, created: false };
+    const held = acquireTaskFolder(root, folder, { pid });
+    if (!held.taken) return refused(held);
+    return {
+      taken: true, heldBy: pid, path: folder, created: false, how: 'kept',
+      branch: record(root, folder)?.branch ?? branch,
+    };
+  }
+
+  // A DIRECTORY GIT KNOWS NOTHING ABOUT, sitting where this folder goes. The
+  // move below cannot be trusted to refuse it: measured 2026-10-07 on git
+  // 2.39.5, `worktree move` onto an existing directory behaves like `mv` and
+  // moves INTO it, so the finished copy landed at `<folder>/.building-<id>` and
+  // the session would have started in a directory holding almost none of the
+  // code. Whatever it is, it is not ours to delete and not ours to fill — an
+  // EMPTY one excepted, since there is nothing there to lose and a stray empty
+  // directory would otherwise wedge the row for good.
+  if (fs.existsSync(folder)) {
+    const empty = tryRead(folder).length === 0;
+    if (!empty) return refused({ reason: 'in-the-way', heldBy: null });
+    try { fs.rmdirSync(folder); } catch { return refused({ reason: 'in-the-way', heldBy: null }); }
   }
 
   // A registration whose directory somebody deleted by hand would refuse the
@@ -187,47 +308,133 @@ export function ensureTaskFolder(dir, id, { pid = process.pid, dependencies = tr
   // EVERY STEP BELOW HAPPENS SOMEWHERE ELSE, and the folder appears at its own
   // path in one move at the end. `buildingFolderPath` is why. A build the app
   // died in the middle of leaves an unfinished copy there, which nobody wants
-  // and which would refuse the next attempt, so it goes first.
+  // and which would refuse the next attempt, so it goes first — unless it
+  // belongs to an app process that is still building it.
   const staging = buildingFolderPath(root, name);
-  clearUnfinished(root, staging);
+  const cleared = clearUnfinished(root, staging, pid);
+  if (!cleared.cleared) return refused({ reason: cleared.reason, heldBy: cleared.heldBy });
 
-  const branchExists = tryGit(root, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`]).ok;
+  const hasBranch = () => tryGit(root, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`]).ok;
+  const branchExists = hasBranch();
   const from = branchExists ? branch : baseRef(root);
-  if (!cloneCheckout(root, staging, branch, from, branchExists)) {
-    // The fast path may have created the branch and then failed the copy.
-    // The branch stays: this file never deletes one. The slow path uses it
-    // when it is already there, which is what `worktree add -b` would refuse.
-    const existsNow = tryGit(root, ['rev-parse', '--verify', '-q', `refs/heads/${branch}`]).ok;
-    const add = existsNow
-      ? tryGit(root, ['worktree', 'add', staging, branch])
-      : tryGit(root, ['worktree', 'add', '-b', branch, staging, baseRef(root)]);
+  let how = 'clone';
+  if (!cloneCheckout(root, staging, branch, from, branchExists, pid)) {
+    how = 'checkout';
+    // THE BRANCH IS ASKED ABOUT AGAIN, AND THAT IS NOT BELT AND BRACES.
+    //
+    // The clone's first act is `worktree add --no-checkout -b`, which CREATES
+    // the branch; the copy and the verification come after. So a clone that
+    // got past its own door and then failed has left the branch behind, on
+    // purpose: `clearUnfinished` keeps it, because a branch outlives every
+    // folder and may already carry commits.
+    //
+    // Reusing the answer from before the clone is how that became the worst
+    // failure in this file. `-b` a second time is refused ("a branch named ...
+    // already exists"), this function throws, and main/supervisor.mjs catches
+    // the throw in two places and hands the session the SHARED CHECKOUT with
+    // nothing but a console line. One recoverable copy failure, and two agents
+    // are editing the same files. Found 2026-10-07 reviewing with Codex
+    // (w-5952e6de3e); the trigger is reproduced in
+    // tests/a-task-whose-first-attempt-failed-still-gets-its-own-folder.
+    //
+    // ATTACH, NEVER `-B` AND NEVER RESET. Whatever is on that branch is work.
+    //
+    // Found twice, independently: the Linux work on main reached the same line
+    // from the other direction, because `cp` there fails differently.
+    const add = hasBranch()
+      ? addOwned(root, staging, [staging, branch], pid)
+      : addOwned(root, staging, ['-b', branch, staging, baseRef(root)], pid);
     if (!add.ok) throw Error(`Could not make a folder for ${name}: ${add.out}`);
-    if (dependencies) cloneDependencies(root, staging);
+  }
+
+  // AND THE LOCAL FILES THE REPOSITORY ASKS FOR, THE SAME WAY WHICHEVER PATH RAN.
+  //
+  // This is the half that was missing, and the half people were complaining
+  // about. The two paths used to disagree: the clone carried every untracked file
+  // in the checkout, the ordinary checkout carried `node_modules` and nothing
+  // else, and which one a task got depended on whether somebody happened to have
+  // an edit open. `.worktreeinclude` makes it one answer, written down, in the
+  // repository, in a file Conductor and Claude Code already read.
+  //
+  // It runs in STAGING, before the folder exists at its own path, so a folder
+  // nobody can see yet is the one that is incomplete. A file that was named and
+  // cannot be given THROWS, and the staging copy goes with it.
+  //
+  // REFUSING THE WHOLE FOLDER IS THE REPORT. There was a version of this that
+  // made the folder anyway and returned the list of what it had refused, and
+  // nothing in the app read that list: a folder starting without its
+  // dependencies, with nobody told, is the fault this was written to end, so it
+  // cannot be how this fails. The throw reaches `_couldNotGetAFolder` in
+  // main/supervisor.mjs, which puts every path and reason on the row where
+  // somebody will read it, and the task waits instead of running wrong.
+  if (dependencies) {
+    try { carryLocalFiles(root, staging); }
+    catch (error) { clearUnfinished(root, staging); throw Error(`Could not make a folder for ${name}: ${error.message}`); }
   }
 
   // `worktree move` rather than a rename, so git's own record of where this
-  // worktree lives moves with it. It refuses if anything is already at the
-  // destination, which is the last guard against walking over a live folder.
-  const moved = tryGit(root, ['worktree', 'move', staging, folder]);
+  // worktree lives moves with it. Twice forced, because a locked worktree is
+  // exactly what this one is and git refuses to move one otherwise; the lock
+  // itself survives the move (git 2.39.5, measured 2026-10-07), which is what
+  // keeps the folder owned from the moment it exists to the moment it is
+  // handed over. The destination was checked above and is checked again here,
+  // since the whole build has run since.
+  if (fs.existsSync(folder)) {
+    clearUnfinished(root, staging, pid);
+    return refused({ reason: 'in-the-way', heldBy: null });
+  }
+  const moved = tryGit(root, ['worktree', 'move', '--force', '--force', staging, folder]);
   if (!moved.ok) {
-    clearUnfinished(root, staging);
+    clearUnfinished(root, staging, pid);
     throw Error(`Could not make a folder for ${name}: ${moved.out}`);
   }
 
-  lock(root, folder, pid);
-  return { path: folder, branch, created: true };
+  const held = acquireTaskFolder(root, folder, { pid });
+  if (!held.taken) return refused(held);
+  return { taken: true, heldBy: pid, path: folder, branch, created: true, how };
 }
 
 /**
- * Throw away an unfinished copy. Nothing is ever lost here: a staging folder
- * has never been handed to anybody, so the most it can hold is a checkout that
- * did not finish. The branch is left alone, as everywhere else in this file.
+ * `git worktree add`, LOCKED IN THE SAME CALL, so the half-built copy is owned
+ * from the moment it exists rather than a moment later. That moment is the one
+ * two app processes over one checkout used to collide in. `--reason` on `add`
+ * arrived in git 2.32; on an older one the lock is written straight after,
+ * which narrows the window rather than closing it and is no reason to refuse
+ * the folder.
  */
-function clearUnfinished(root, staging) {
-  if (!fs.existsSync(staging) && !record(root, staging)) return;
+function addOwned(root, folder, rest, pid) {
+  const owned = tryGit(root, ['worktree', 'add', '--lock', '--reason', lockReason(pid), ...rest]);
+  if (owned.ok) return owned;
+  const added = tryGit(root, ['worktree', 'add', ...rest]);
+  if (added.ok) tryGit(root, ['worktree', 'lock', '--reason', lockReason(pid), folder]);
+  return added;
+}
+
+/**
+ * Throw away an unfinished copy, UNLESS SOMEBODY IS STILL MAKING IT. Nothing is
+ * ever lost in the clearing: a staging folder has never been handed to anybody,
+ * so the most it can hold is a checkout that did not finish. The branch is left
+ * alone, as everywhere else in this file.
+ *
+ * The refusal is the part that was missing. Inside one process the folder
+ * thread serialises these, so a staging folder on disk really was abandoned.
+ * Across two it was not, and here that is routine: one app runs from the app
+ * folder and one from a checkout. Since the local files started being carried
+ * in, the build is slower, so the window is wider.
+ */
+function clearUnfinished(root, staging, pid = process.pid) {
+  if (!fs.existsSync(staging) && !record(root, staging)) return { cleared: true };
+  const held = holder(root, staging, pid);
+  if (!held.ok) {
+    return { cleared: false, reason: held.reason === 'held' ? 'building' : held.reason, heldBy: held.heldBy };
+  }
+  // Unlocked first: `worktree remove` refuses a locked worktree even with one
+  // `--force`, and this one is ours or its owner is gone.
+  tryGit(root, ['worktree', 'unlock', staging]);
   tryGit(root, ['worktree', 'remove', '--force', staging]);
   try { fs.rmSync(staging, { recursive: true, force: true }); } catch { /* already gone */ }
   tryGit(root, ['worktree', 'prune']);
+  return { cleared: true };
 }
 
 /**
@@ -249,20 +456,13 @@ function clearUnfinished(root, staging) {
  * ordinary checkout runs. A fast folder that is subtly not the code would be
  * far worse than a slow one.
  *
- * THE COPY IS THE PLATFORM'S OWN CLONE. macOS `cp -c` is APFS clonefile.
- * GNU `cp -a --reflink=auto` shares blocks where the filesystem can and
- * copies where it cannot. `-c` is not an option there, and a copy that
- * failed used to leave the branch the fast path had just created, so the
- * ordinary checkout then died with "a branch named … already exists".
+ * THE COPY IS THE PLATFORM'S OWN CLONE, and it lives in
+ * `main/worktree-include.mjs` because both files need it and that one does not
+ * import this one. macOS `cp -c` is APFS clonefile; GNU `cp -a --reflink=auto`
+ * shares blocks where the filesystem can and copies where it cannot, and `-c`
+ * is not an option there at all.
  */
-function copyTree(from, to) {
-  const args = process.platform === 'darwin'
-    ? ['-c', '-R', from, to]
-    : ['-a', '--reflink=auto', from, to];
-  execFileSync('cp', args, { stdio: ['ignore', 'ignore', 'pipe'] });
-}
-
-function cloneCheckout(root, folder, branch, from, branchExists) {
+function cloneCheckout(root, folder, branch, from, branchExists, pid = process.pid) {
   // TRACKED CONTENT ONLY, on both sides of this. Her checkout permanently
   // carries a couple of untracked files (a scratch `:memory:.ses`, a folder of
   // screenshots somebody left), and counting those as dirty turned the fast
@@ -276,18 +476,37 @@ function cloneCheckout(root, folder, branch, from, branchExists) {
   if (!clean.ok || clean.out.length > 0) return false;
 
   const add = branchExists
-    ? tryGit(root, ['worktree', 'add', '--no-checkout', folder, branch])
-    : tryGit(root, ['worktree', 'add', '--no-checkout', '-b', branch, folder, from]);
+    ? addOwned(root, folder, ['--no-checkout', folder, branch], pid)
+    : addOwned(root, folder, ['--no-checkout', '-b', branch, folder, from], pid);
   if (!add.ok) return false;
 
   try {
-    for (const entry of fs.readdirSync(root)) {
-      if (entry === '.git' || entry === WORKTREES[0]) continue;
-      copyTree(path.join(root, entry), folder);
+    // THE ENTRIES THAT HOLD TRACKED CONTENT, AND NOT SIMPLY EVERYTHING.
+    //
+    // It used to be every top-level entry except `.git` and `.claude`, which had
+    // two faults. The small one: every untracked file in the checkout rode along,
+    // so this path and the ordinary one produced different folders. The large
+    // one: skipping `.claude` WHOLESALE means a repository that commits a file
+    // under it (a `.claude/settings.json`, which is ordinary) failed this
+    // function's own verification every single time, because the clone was
+    // missing a tracked file. That failure is how a task ended up in the shared
+    // checkout; see the comment in `ensureTaskFolder` about asking for the
+    // branch twice.
+    const tracked = trackedTopLevel(root);
+    // A repository with a submodule is the ordinary checkout's business: a
+    // gitlink is a pointer, not a directory of files, and `worktree move`
+    // refuses a worktree holding one.
+    if (tracked.submodules) throw Error('this repository has submodules');
+    for (const entry of tracked.entries) {
+      if (entry === '.git') continue;
+      copyIn(root, folder, entry);
     }
     if (!tryGit(folder, ['reset', '-q', 'HEAD']).ok) throw Error('the index would not fill in');
     const after = tryGit(folder, ['status', '--porcelain', '--untracked-files=no']);
     if (!after.ok || after.out.length > 0) throw Error('the clone did not match the commit');
+    // An ignored file inside a tracked directory came with it (`renderer/dist`).
+    // Cleared here, and whatever is genuinely wanted arrives by name afterwards.
+    onlyTrackedContent(folder);
     return true;
   } catch {
     // Back to nothing, so the ordinary path starts from a clean sheet. What is
@@ -295,11 +514,30 @@ function cloneCheckout(root, folder, branch, from, branchExists) {
     // `folder` is the staging path, which no session has ever been given. It
     // used to be the real one, and a `remove --force` of that is how a running
     // agent lost the ground under it.
-    clearUnfinished(root, folder);
+    clearUnfinished(root, folder, pid);
     return false;
   }
 }
 
+/**
+ * One top-level entry, cloned into the new folder.
+ *
+ * `.claude` IS THE ONE ENTRY THAT CANNOT BE COPIED WHOLE, because the folders
+ * every other task is working in live inside it. Its children are copied one by
+ * one instead, with `worktrees` left out, so a repository that tracks a file
+ * under `.claude` gets it and no task ever receives a copy of another task's
+ * work.
+ */
+function copyIn(root, folder, entry) {
+  if (entry !== WORKTREES[0]) { copyTree(path.join(root, entry), folder); return; }
+  const to = path.join(folder, entry);
+  fs.mkdirSync(to, { recursive: true });
+  for (const child of fs.readdirSync(path.join(root, entry))) {
+    if (child === WORKTREES[1]) continue;
+    copyTree(path.join(root, entry, child), to);
+  }
+}
+
 /**
  * Task folders live inside the repository, where the checkout would otherwise
  * report them as untracked and every review card built in the shared checkout
@@ -319,32 +557,14 @@ function hideFromTheCheckout(root) {
   } catch { /* an unwritable git dir is not a reason to refuse the folder */ }
 }
 
-/**
- * Dependencies, cloned rather than copied. Measured 2026-09-22: `cp -c` of this
- * repository's 929 MB node_modules took 2.9 seconds and moved the volume's free
- * space by nothing at all, because APFS shares the blocks until something
- * writes. A plain copy is a minute and a real gigabyte, which is most of what
- * the 26 GB on her Mac was. Failure here is never fatal: the folder is still a
- * good folder, it just has to install for itself.
- */
-function cloneDependencies(root, folder) {
-  const from = path.join(root, 'node_modules');
-  const to = path.join(folder, 'node_modules');
-  if (!fs.existsSync(from) || fs.existsSync(to)) return false;
-  try {
-    copyTree(from, to);
-    return true;
-  } catch {
-    try { fs.rmSync(to, { recursive: true, force: true }); } catch { /* nothing to undo */ }
-    return false;
-  }
-}
-
-function lock(root, folder, pid) {
-  const held = record(root, folder)?.lock;
-  if (held !== undefined && pidInReason(held) !== pid) return;
-  if (held === undefined) tryGit(root, ['worktree', 'lock', '--reason', lockReason(pid), folder]);
-}
+// DEPENDENCIES USED TO BE SPECIAL-CASED HERE, and now they are one line of a
+// list the repository writes: `main/worktree-include.mjs`, whose default when a
+// repository says nothing is `/node_modules`, so the behaviour this paragraph
+// used to describe is still the behaviour. The measurement that justified it
+// stands and belongs with the code that does it now: cloning this repository's
+// 929 MB of dependencies took 2.9 seconds on 2026-09-22 and moved the volume's
+// free space by nothing at all, because APFS shares the blocks until something
+// writes.
 
 /** Is there anything in here that deleting the folder would lose? */
 export function folderState(root, folder) {
@@ -356,21 +576,46 @@ export function folderState(root, folder) {
   return { dirty, merged };
 }
 
+/**
+ * THE FOLDER A CALL IS ABOUT IS THE ONE IT WAS HANDED, NEVER ONE REBUILT FROM A
+ * BASENAME (w-330eea6c66).
+ *
+ * `releaseTaskFolder` and `parkTaskFolder` used to take a task id and work out
+ * `.claude/worktrees/<id>` from it. That is correct while the only caller is a
+ * row's own session, and it is the bug the moment anything passes on a folder it
+ * found: the sweep walks a list of folders, and a stray whose basename happened
+ * to read like a task id would have had the app committing in, and deleting,
+ * whatever sat at the reconstructed path instead.
+ *
+ * So a caller holding a path says so, and a path that is not this task's own
+ * folder is refused rather than quietly swapped for one. Called with no path at
+ * all it answers exactly as it always did, which is every ordinary call.
+ */
+function ownFolder(root, name, given) {
+  const mine = taskFolderPath(root, name);
+  if (given === null || given === undefined) return mine;
+  return real(given) === mine ? mine : null;
+}
+
 /**
  * Give the folder back when the session is done with it. Removal is the rare
  * case on purpose: it happens when the work is already in main and nothing is
  * uncommitted. Every other answer names what is in the way, so the app can say
  * it rather than leave another invisible folder on her disk.
  */
-export function releaseTaskFolder(dir, id, { pid = process.pid } = {}) {
+export function releaseTaskFolder(dir, id, { pid = process.pid, path: given = null } = {}) {
   const name = safeTaskName(id);
   const root = repoRoot(dir);
   if (!root) return { removed: false, reason: 'no-repo' };
-  const folder = taskFolderPath(root, name);
+  const folder = ownFolder(root, name, given);
+  if (!folder) return { removed: false, reason: 'not-ours', path: given };
   if (!fs.existsSync(folder)) return { removed: false, reason: 'gone' };
 
-  const holder = pidInReason(record(root, folder)?.lock);
-  if (holder && holder !== pid && alive(holder)) return { removed: false, reason: 'held', path: folder };
+  // Whose folder this is, asked in the one place that knows (`holder`). A lock
+  // naming a process that has exited is not a claim on anything, and sweeping
+  // those is most of what this function is for.
+  const held = holder(root, folder, pid);
+  if (!held.ok) return { removed: false, reason: held.reason, heldBy: held.heldBy, path: folder };
 
   const { dirty, merged } = folderState(root, folder);
   if (dirty) return { removed: false, reason: 'uncommitted', path: folder };
@@ -387,6 +632,14 @@ export function releaseTaskFolder(dir, id, { pid = process.pid } = {}) {
 /** The subject line that marks a commit as work parked rather than finished. */
 export const PARKED = 'Parked when the task was closed';
 
+/**
+ * And the one under it, which holds what was STAGED when the task was closed.
+ * Two commits rather than one because `git add -A` replaces the index with the
+ * working tree, so a single commit cannot carry both and the staged arrangement
+ * was the half that went.
+ */
+export const PARKED_INDEX = 'Parked when the task was closed (what was staged)';
+
 /**
  * CLOSING A TASK PARKS ITS FOLDER, AND PARKING LOSES NOTHING.
  *
@@ -413,25 +666,46 @@ export const PARKED = 'Parked when the task was closed';
  * wrote itself goes. That is the same boundary as removing any worktree, and the
  * alternative is committing secrets onto a branch.
  */
-export function parkTaskFolder(dir, id, { pid = process.pid } = {}) {
+export function parkTaskFolder(dir, id, { pid = process.pid, path: given = null } = {}) {
   const name = safeTaskName(id);
   const root = repoRoot(dir);
   if (!root) return { parked: false, reason: 'no-repo' };
-  const folder = taskFolderPath(root, name);
+  // `ownFolder`, and never the basename of whatever we were pointed at: parking
+  // commits and then removes, so being wrong here costs somebody their folder.
+  const folder = ownFolder(root, name, given);
+  if (!folder) return { parked: false, reason: 'not-ours', path: given };
   if (!fs.existsSync(folder)) return { parked: false, reason: 'gone' };
 
-  const holder = pidInReason(record(root, folder)?.lock);
-  if (holder && holder !== pid && alive(holder)) return { parked: false, reason: 'held', path: folder };
+  const owner = holder(root, folder, pid);
+  if (!owner.ok) return { parked: false, reason: owner.reason, heldBy: owner.heldBy, path: folder };
 
   const { dirty } = folderState(root, folder);
   let kept = 'nothing uncommitted';
   if (dirty) {
+    // TWO COMMITS, BECAUSE THE INDEX IS WORK TOO. `git add -A` replaces the
+    // index with the working tree, so parking used to flatten them into one:
+    // stage version A of a file, edit the working copy to B, park, and B was
+    // all that came back. The staged arrangement an agent had built — a
+    // half-prepared commit, a rename, a file added but not yet written to —
+    // was gone, and the round trip was documented as keeping it.
+    //
+    // So the index is committed FIRST, exactly as it stands, and the working
+    // tree second. The two trees are then both on the branch, and
+    // `restoreTaskFolder` unwinds them into the index and the working tree they
+    // came from. `--allow-empty` because an index that matches HEAD is the
+    // ordinary case and is still the thing to come back to.
+    // AND AN INDEX THAT WILL NOT COMMIT ON ITS OWN IS NOT A REASON TO REFUSE.
+    // A merge or rebase an agent left mid-flight has unmerged paths, which git
+    // will not commit, and the `add -A` below is what resolves them. Losing the
+    // index there is exactly the old behaviour, and the old behaviour is better
+    // than stranding the folder.
+    tryGit(folder, ['commit', '--no-verify', '--allow-empty', '-q', '-m', PARKED_INDEX]);
     const staged = tryGit(folder, ['add', '-A']);
     // `--no-verify`, because a repository's own commit hooks are written for a
     // person finishing a piece of work, and this is the app tidying up after
     // one. A hook that refuses here would strand the folder it is protecting.
-    const held = tryGit(folder, ['commit', '--no-verify', '-q', '-m', PARKED]);
-    if (!staged.ok || !held.ok) return { parked: false, reason: 'refused', path: folder, detail: held.out };
+    const tree = tryGit(folder, ['commit', '--no-verify', '--allow-empty', '-q', '-m', PARKED]);
+    if (!staged.ok || !tree.ok) return { parked: false, reason: 'refused', path: folder, detail: tree.out };
     kept = 'work in progress';
   }
 
@@ -442,46 +716,164 @@ export function parkTaskFolder(dir, id, { pid = process.pid } = {}) {
 }
 
 /**
- * The way back. Makes the folder again off the branch, and when the last commit
- * on it is a parked one, takes that commit apart so the work is uncommitted
- * exactly as it was. Undoing it rather than leaving it is what stops a row she
- * opens and closes five times from growing five commits nobody wrote.
+ * The way back. Makes the folder again off the branch, and when the last
+ * commits on it are parked ones, takes them apart so the work is uncommitted
+ * exactly as it was: THE WORKING TREE FROM ONE AND THE INDEX FROM THE OTHER.
+ *
+ *   `reset HEAD~1` is mixed, so it leaves the files alone and fills the index
+ *   in from the commit below — which is the index as it was parked.
+ *   `reset --soft HEAD~1` then puts HEAD back where it started and touches
+ *   neither, so the branch grows nothing and both halves survive.
+ *
+ * A FOLDER PARKED BEFORE THIS LANDED has one commit and no index commit under
+ * it, and still has to come back: there are parked branches on this Mac from
+ * the old shape. One mixed reset is what it always was.
  */
 export function restoreTaskFolder(dir, id, { pid = process.pid } = {}) {
   const made = ensureTaskFolder(dir, id, { pid });
-  if (!made) return null;
+  if (!made || made.taken === false) return made ?? null;
   const last = tryGit(made.path, ['log', '-1', '--format=%s']);
-  if (last.ok && last.out === PARKED) tryGit(made.path, ['reset', '-q', 'HEAD~1']);
+  if (!last.ok || last.out !== PARKED) return made;
+  const under = tryGit(made.path, ['log', '-1', '--format=%s', 'HEAD~1']);
+  tryGit(made.path, ['reset', '-q', 'HEAD~1']);
+  if (under.ok && under.out === PARKED_INDEX) tryGit(made.path, ['reset', '--soft', '-q', 'HEAD~1']);
   return made;
 }
 
+/**
+ * EVERY COPY OF THIS PROJECT ON THE DISK, WHOEVER MADE IT. INVENTORY, NOT
+ * OWNERSHIP, AND THE TWO BEING ONE QUESTION IS WHAT STRANDED 740 MB.
+ *
+ * MEASURED 2026-10-07 (w-5952e6de3e). Thirteen worktrees of this repository
+ * existed outside `.claude/worktrees/`: nine beside the checkout as
+ * `agentbox-team-<name>`, one under `/private/tmp`, one as `wt-<task id>`. About
+ * 740 MB of tracked files, every one made by hand by some session rather than by
+ * the app. `listTaskFolders` filtered on the folder's parent being the app's own
+ * home, so not one of them could be listed, shown or swept: the same
+ * invisibility that stranded 26 GB on 2026-09-22, in a new place. One of them had
+ * `node_modules` symlinked back to the shared checkout, so an `npm install`
+ * inside it rewrote every other folder's dependencies.
+ *
+ * AND WIDENING THAT FILTER WOULD HAVE BEEN WORSE THAN THE BUG, which is why this
+ * is a second question rather than a looser version of the first one. The
+ * supervisor feeds the list into automatic parking, and parking rebuilt
+ * `.claude/worktrees/<id>` out of the folder's BASENAME rather than using the
+ * path it was handed. A folder nobody's row owns passes every eligibility check
+ * parking has, so a wider list would have had the app committing to a branch it
+ * invented and deleting a folder somebody made on purpose.
+ *
+ * So: this answers what is there, and `ours` answers what the app may act on.
+ * Only the second is ever parked or removed, and the first is what lets a person
+ * see what is holding their disk.
+ *
+ * `ours` IS PROOF BY LOCATION, and the location is the app's own. Nothing but
+ * `ensureTaskFolder` puts a folder at `<primary>/.claude/worktrees/<task name>`,
+ * so a folder there was made here. It is deliberately not inferred from the lock
+ * (dropped on the way to every removal) or from a marker file (which an agent
+ * working in the folder could delete, turning a folder the app made into one it
+ * will never reclaim).
+ */
+export function inventoryWorktrees(dir) {
+  const root = repoRoot(dir);
+  if (!root) return [];
+  const list = registered(root);
+  // GIT LISTS THE MAIN WORKTREE FIRST, and the home hangs off that one rather
+  // than off whichever folder we were asked from: `rev-parse --show-toplevel`
+  // inside a linked worktree answers with that worktree, so deriving the home
+  // from it would call every real task folder a stray.
+  const primary = real(list[0]?.path ?? root);
+  const home = path.join(primary, ...WORKTREES);
+  return list.map((w) => {
+    const at = real(w.path);
+    const name = path.basename(at);
+    const unfinished = name.startsWith(BUILDING);
+    const missing = !fs.existsSync(at);
+    const holder = pidInReason(w.lock);
+    return {
+      path: at,
+      // What the registration spells it, which on a Mac can be the other side of
+      // a symlink: `/tmp/x` against `/private/tmp/x`.
+      registeredAs: w.path,
+      primary: at === primary,
+      branch: w.branch ?? '',
+      lock: w.lock ?? null,
+      heldBy: holder && alive(holder) ? holder : null,
+      // A folder still being built is the app's and is wanted by nobody: it has
+      // no row standing in it, so it may never be listed, shown or swept.
+      unfinished,
+      missing,
+      prunable: !!w.prunable,
+      // WHERE THE APP PUTS ITS OWN, whether or not anything is there now. Kept
+      // apart from `ours` because a registration whose folder has gone is still
+      // the app's bookkeeping to tidy, and is nothing anybody may act on.
+      atOurPath: path.dirname(at) === home && couldBeATaskName(name),
+      ours: !unfinished && !missing && !w.prunable
+        && path.dirname(at) === home && couldBeATaskName(name),
+    };
+  });
+}
+
+/**
+ * Copies of this project the app did not make, so a person can see what is
+ * holding their disk. The checkout itself is not one of them, and neither is a
+ * registration pointing at nothing: that is a different fact with its own field
+ * and its own answer, `pruneMissingWorktrees`.
+ */
+export function strayWorktrees(dir) {
+  return inventoryWorktrees(dir)
+    .filter((w) => !w.primary && !w.ours && !w.unfinished && !w.missing && !w.prunable);
+}
+
+/**
+ * REGISTRATIONS POINTING AT NOTHING, DROPPED. One of the thirteen lived under
+ * `/private/tmp`, which macOS may purge from under it, and git goes on holding
+ * the registration: that is what refuses the next `worktree add` at that path
+ * with "already registered".
+ *
+ * Nothing can be lost here, by git's own definition of `prune`: it only ever
+ * drops the bookkeeping for a worktree whose directory is already gone, and the
+ * branch it stood on survives, as every branch survives everything in this file.
+ * A folder of OURS is unlocked first, because `prune` skips a locked worktree and
+ * the app locks every folder it makes, which would otherwise leave the
+ * registration of a deleted folder wedged there forever.
+ */
+export function pruneMissingWorktrees(dir) {
+  const root = repoRoot(dir);
+  if (!root) return [];
+  const gone = inventoryWorktrees(dir).filter((w) => !w.primary && (w.missing || w.prunable));
+  if (!gone.length) return [];
+  for (const w of gone) if (w.atOurPath) tryGit(root, ['worktree', 'unlock', w.path]);
+  tryGit(root, ['worktree', 'prune']);
+  const left = new Set(inventoryWorktrees(dir).map((w) => w.path));
+  return gone.map((w) => w.path).filter((at) => !left.has(at));
+}
+
 /**
  * Every task folder in this repository and what would be lost by deleting it.
  * This is what the app reads to show her a folder that is holding work, which
  * is the half that did not exist: hers held 26 GB and she had never seen one.
+ *
+ * THE OWNERSHIP VIEW, and the only list anything automatic is allowed to act on.
+ * `inventoryWorktrees` above is the wider one, and the comment there is why they
+ * are not the same list.
  */
 export function listTaskFolders(dir) {
   const root = repoRoot(dir);
   if (!root) return [];
-  const home = path.join(root, ...WORKTREES);
-  return registered(root)
-    // A folder still being built is not one of hers: it has no row standing in
-    // it and nothing in it is wanted, so it may never be listed, shown or swept.
-    .filter((w) => path.dirname(w.path) === home && !w.prunable
-      && !path.basename(w.path).startsWith(BUILDING))
+  return inventoryWorktrees(dir)
+    .filter((w) => w.ours)
     .map((w) => {
       const { dirty, merged } = folderState(root, w.path);
       let touchedAt = null;
       try { touchedAt = fs.statSync(w.path).mtimeMs; } catch { /* it can vanish under us */ }
-      const holder = pidInReason(w.lock);
       return {
         id: path.basename(w.path),
         path: w.path,
-        branch: w.branch ?? '',
+        branch: w.branch,
         dirty,
         merged,
         touchedAt,
-        heldBy: holder && alive(holder) ? holder : null,
+        heldBy: w.heldBy,
       };
     });
 }