agentbox-app 0.1.13 → 0.1.16

package/main/task-folders.mjs

@@ -62,7 +62,7 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { nameSlug } from '../shared/product-name.mjs';
+import { Name, 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. */
@@ -77,7 +77,20 @@ const SAFE_NAME = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
 /** What an unfinished folder is called. A task name may never start with a dot. */
 const BUILDING = '.building-';
 
-const git = (cwd, args) => execFileSync('git', args, {
+// A HOOK RUN BY THE APP IN A TASK FOLDER IS A WORKER'S CODE RUN AS THE APP.
+// core.hooksPath is often the relative 'scripts/hooks', which git resolves
+// against the working tree it runs in, so in a task folder it is that folder's
+// own scripts/hooks -- which a worker edits. parkTaskFolder commits there
+// (post-commit, reference-transaction), so the app's every git in a linked
+// worktree runs hook-free. The primary checkout, where `worktree add` runs its
+// own post-checkout, keeps its hooks: a linked worktree's `.git` is a file.
+const inLinkedWorktree = (cwd) => {
+  try { return fs.lstatSync(path.join(cwd, '.git')).isFile(); } catch { return false; }
+};
+const git = (cwd, args) => execFileSync('git', [
+  ...(inLinkedWorktree(cwd) ? ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false'] : []),
+  ...args,
+], {
   cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'],
 }).trim();
 
@@ -90,12 +103,66 @@ function tryRead(dir) {
   try { return fs.readdirSync(dir); } catch { return ['we could not look']; }
 }
 
+// Files that say nothing of anyone's work: Finder's, and the one an agent
+// writes when it recreates its deleted folder to keep its shell alive. A
+// folder holding only these is as good as empty.
+const LEFTOVER_MARKERS = new Set(['.DS_Store', '.keep-session']);
+const isPlainFile = (file) => { try { return fs.lstatSync(file).isFile(); } catch { return false; } };
+
 /** 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() }; }
 }
 
+/**
+ * DOES THIS FAILED `worktree add` MEAN SOMEBODY ELSE IS MAKING THE FOLDER?
+ *
+ * Git's wordings for "something is already at that path", measured on git
+ * 2.39.5 across six processes racing for one id:
+ *
+ *   fatal: '<staging>' already exists                   (2026-10-09)
+ *   fatal: '<staging>' is already registered            (2026-10-09)
+ *   fatal: '<branch>' is already checked out at '<staging>'
+ *   fatal: '<branch>' is already used by worktree at '<staging>'
+ *   fatal: '<staging>' is not a working tree            (2026-10-17)
+ *
+ * THE NARROWNESS IS THE POINT, AND IT TOOK TWO GOES. Everything else `worktree
+ * add` can fail with -- a full disk, an invalid ref, a branch collision -- is a
+ * real failure with a different answer, and reporting one of those as "another
+ * session has this" would send whoever reads the row hunting for a session that
+ * does not exist. So a wording is not enough on its own: the path git names has
+ * to be a STAGING folder. Named anywhere else, the two branch wordings mean the
+ * branch is checked out in somebody's finished work, which is a failure a
+ * person must act on -- `a-task-folder-is-made-when-the-repository-has-a-
+ * failing-post-checkout-hook` is main's test for exactly that, and the first
+ * draft of this guard swallowed it.
+ *
+ * A branch collision is deliberately not matched either: `a branch named ...
+ * already exists` has its own road a few lines above (ask again, then attach),
+ * and that road is the 2026-10-07 fix which must not be routed around.
+ */
+export function somebodyIsBuilding(out) {
+  const said = String(out ?? '');
+  if (!said) return false;
+  // A BRANCH THAT ALREADY EXISTS IS NOT A FOLDER THAT ALREADY EXISTS, and it
+  // shares the words. It has its own road a few lines above `addOwned`'s caller
+  // -- ask again, then attach -- and that road is the 2026-10-07 fix, so routing
+  // around it would hand a session the shared checkout. Checked first, because
+  // the phrase it carries would otherwise match the clause below it.
+  if (/a branch named/i.test(said)) return false;
+  // The marker rather than the path itself, because git prints the path it
+  // resolved: on a Mac a staging folder under /tmp comes back under /private.
+  if (!said.includes(BUILDING)) return false;
+  return /already exists/i.test(said)
+    || /already registered/i.test(said)
+    || /already used by worktree/i.test(said)
+    || /already checked out/i.test(said)
+    // Git's bookkeeping for staging caught mid-flight: registered by the winner
+    // and already gone from the disk, so the loser's second add finds neither.
+    || /is not a working tree/i.test(said);
+}
+
 /** `safeTaskName`'s question, asked of a folder already on the disk without throwing. */
 const couldBeATaskName = (name) => SAFE_NAME.test(name) && String(name).length <= 64;
 
@@ -154,6 +221,132 @@ export function repoRoot(dir) {
   return found.ok && found.out ? found.out : null;
 }
 
+/**
+ * A PROJECT FOLDER THAT IS NOT A REPOSITORY IS MADE ONE (2026-10-14).
+ *
+ * A teammate's first task failed with "no folder could be made" until they ran
+ * `git init` and a first commit by hand, and so did every task in any project
+ * picked from a plain folder: a task folder is a worktree, and a worktree needs
+ * a repository and a commit to start from. New Project even creates the folder
+ * when it is missing, so an empty one failed its first task every time.
+ *
+ * So the app takes the same two steps. Local only: nothing is pushed, and a
+ * `.gitignore` the folder already has is respected by the first commit. Inside
+ * a repository already, `repoRoot` answers first and this never runs. A folder
+ * too big to commit by itself (`FIRST_COMMIT_LIMIT`) is left exactly as it was,
+ * the repository just started here removed again, and the refusal says why.
+ */
+function startRepository(dir) {
+  if (!dir || !fs.existsSync(dir)) return null;
+  const why = gitWillNotRun(dir);
+  if (why) throw Error(why);
+  if (!tryGit(dir, ['init', '-q']).ok) return null;
+  const root = repoRoot(dir);
+  try { firstCommitIfNone(root); }
+  catch (error) { fs.rmSync(path.join(root, '.git'), { recursive: true, force: true }); throw error; }
+  return root;
+}
+
+/**
+ * WHEN GIT ITSELF CANNOT RUN HERE, THE ONE THING TO DO ABOUT IT (2026-10-15).
+ *
+ * `repoRoot` reads every failure as "not a repository", and two everyday setups
+ * fail before git looks at anything: a Mac without the Command Line Tools,
+ * whose `/usr/bin/git` only prints "xcrun: error: invalid active developer
+ * path", and a repository owned by another account, which git refuses as
+ * "dubious ownership". Both ended as "no folder could be made" with a list of
+ * causes that named neither, and the second ran `git init` over somebody
+ * else's repository on the way. The sentence returned here is what the task's
+ * row says, after "could not be given a folder of its own to work in: ".
+ */
+function gitWillNotRun(dir) {
+  const asked = tryGit(dir, ['rev-parse', '--show-toplevel']);
+  if (asked.ok) return null;
+  if (/xcrun: error|invalid active developer path|no developer tools were found/i.test(asked.out)) {
+    return `git is not set up on this Mac yet. Open Terminal, run xcode-select --install, and reply here once it has finished`;
+  }
+  if (/\bENOENT\b/.test(asked.out)) {
+    return `git is not installed on this computer, and ${Name} needs it to give each task a folder. Install git, then reply here`;
+  }
+  const owned = /dubious ownership in repository at '([^']+)'/.exec(asked.out);
+  if (owned) {
+    return `git will not work in ${owned[1]} because that folder belongs to another account on this computer. If it is yours, run git config --global --add safe.directory '${owned[1]}' in Terminal, then reply here`;
+  }
+  return null;
+}
+
+/**
+ * HOW MUCH A FIRST COMMIT MAY TAKE ON BY ITSELF. Measured on the founder's
+ * store on 2026-10-14: the one project whose folder was not a repository held
+ * 18 GB, mostly media libraries, and committing that copies all of it into
+ * `.git` and runs for minutes. A code project with its dependencies left in is
+ * a few hundred MB.
+ */
+const FIRST_COMMIT_LIMIT = 500 * 1024 * 1024;
+
+const sizeSaid = (bytes) => (bytes >= 1024 ** 3
+  ? `${(bytes / 1024 ** 3).toFixed(1)} GB`
+  : `${Math.round(bytes / 1024 ** 2)} MB`);
+
+/** What a first commit would take, in bytes, stopping once past the limit. */
+function sizeOfFirstCommit(root) {
+  // Its own call rather than `tryGit`, for the buffer: a folder of media lists
+  // far past the default megabyte of output.
+  const listed = execFileSync('git', ['ls-files', '-z', '--cached', '--others', '--exclude-standard'], {
+    cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 256 * 1024 * 1024,
+  });
+  let total = 0;
+  for (const file of listed.split('\0')) {
+    if (!file) continue;
+    try { total += fs.lstatSync(path.join(root, file)).size; } catch { /* gone since the listing */ }
+    if (total > FIRST_COMMIT_LIMIT) break;
+  }
+  return total;
+}
+
+/**
+ * The first commit, made only when there is none: a repository with any commit
+ * at all is never committed to here, so work somebody has not committed stays
+ * theirs. `--allow-empty` because an empty folder is a real first project.
+ * Made `asTheApp`, like every commit in this file.
+ */
+function firstCommitIfNone(root) {
+  if (tryGit(root, ['rev-parse', '--verify', '-q', 'HEAD']).ok) return;
+  hideFromTheCheckout(root);
+  const size = sizeOfFirstCommit(root);
+  if (size > FIRST_COMMIT_LIMIT) {
+    throw Error(`this project's folder is not a git repository yet, and at more than ${sizeSaid(size)} it is too big for ${Name} to make one by itself. In a terminal in that folder run git init, add a .gitignore for the big folders, and make a first commit`);
+  }
+  if (!tryGit(root, ['add', '-A']).ok) return;
+  tryGit(root, [...asTheApp(root), 'commit', '-q', '--no-verify', '--allow-empty', '-m', `First commit, made by ${Name} so each task can have a folder of its own`]);
+}
+
+/**
+ * EVERY COMMIT THE APP MAKES IS MADE WITH NOBODY WATCHING, so it cannot ask
+ * anybody anything. Two things a person's git setup can make a commit ask:
+ *
+ *   Who are you. A git with no name or email set refuses with "Please tell me
+ *   who you are" wherever it cannot make one up, which is any repository with
+ *   `user.useConfigOnly` and any Linux whose host name has no domain. A park
+ *   refused that way left the folder on the disk for good (2026-10-15). So
+ *   whatever is missing is filled in with the app's name, and whatever the
+ *   person set is kept.
+ *
+ *   A passphrase. With `commit.gpgsign` on, the signer can open a pinentry
+ *   window or wait on 1Password, and measured on 2026-10-15 with a signer that
+ *   waits, a park never came back. Folder jobs run one at a time, so that one
+ *   park left every later task in every project without a folder. Signing is
+ *   off for the app's commits only; the person's own still sign.
+ */
+function asTheApp(cwd) {
+  const set = (key) => { const got = tryGit(cwd, ['config', key]); return got.ok && got.out !== ''; };
+  return [
+    ...(set('user.name') ? [] : ['-c', `user.name=${Name}`]),
+    ...(set('user.email') ? [] : ['-c', `user.email=${nameSlug}@localhost`]),
+    '-c', 'commit.gpgsign=false',
+  ];
+}
+
 /**
  * What a new folder starts from: LOCAL main, not the remote. Local main carries
  * whatever has not been pushed, and on this Mac that is routinely 20+ commits,
@@ -219,6 +412,48 @@ function holder(root, folder, pid) {
   return { ok: true, heldBy: owner, stale: true };
 }
 
+/**
+ * WHO ENDED UP IN THE LOCK, read off our own `worktree lock` and the lock as it
+ * stands a moment later. Four answers and one non-answer:
+ *
+ *   our pid in it            ours
+ *   another pid in it        theirs, and the row can name it
+ *   a lock with no pid       a person locked it by hand
+ *   our lock would not write this machine failing, in git's own words
+ *   nothing in it at all     NOT AN ANSWER YET: ask again
+ *
+ * THE NON-ANSWER IS THE WHOLE POINT. `unlock` and `lock` are two commands, so
+ * while another session takes the same dead owner's folder over, there is a
+ * moment when the folder carries no lock at all: ours is gone and theirs is not
+ * written yet. A read landing in that moment has nobody to name, and it used to
+ * answer `refused`, which reached the row as "its folder is refused" -- not
+ * something anybody can act on, and not true either, since that session is
+ * about to own it. Asked again, the lock has landed and the answer is real.
+ *
+ * GIT'S OWN REFUSAL IS READ RATHER THAN COUNTED AS A FAILURE. `is already
+ * locked` is a session that got in a moment before us and usually carries its
+ * pid, so it asks again too and names them when the asking runs out. Only a
+ * lock git would not write for some other reason -- a permission, a full disk,
+ * a path it does not know -- is this machine failing, and that one carries
+ * git's words out rather than naming a session that does not exist.
+ */
+const alreadyLocked = (out) => /is already locked/i.test(String(out ?? ''));
+
+export function whoEndedUpInTheLock({ pid, locked, after, triesLeft }) {
+  const now = pidInReason(after);
+  if (now === pid) return { taken: true, heldBy: pid };
+  if (after !== undefined) return { taken: false, reason: now ? 'held' : 'locked', heldBy: now ?? null };
+  if (!locked.ok && !alreadyLocked(locked.out)) {
+    return { taken: false, reason: 'unlockable', heldBy: null, detail: locked.out };
+  }
+  if (triesLeft > 0) return { again: true };
+  const them = pidInReason(locked.out);
+  if (them) return { taken: false, reason: 'held', heldBy: them };
+  // Git saw a lock we cannot read a pid out of, which is a person's own.
+  if (!locked.ok) return { taken: false, reason: 'locked', heldBy: null };
+  return { taken: false, reason: 'held', heldBy: null };
+}
+
 /**
  * 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.
@@ -229,20 +464,24 @@ function holder(root, folder, pid) {
  * 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.
+ *
+ * Asked up to `tries` times, because the read-back can land between another
+ * taker's unlock and its lock and see nobody at all. Each try is a fresh
+ * `worktree list`, which is the only pause the gap needs: the gap is one git
+ * command wide.
  */
-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 };
+export function acquireTaskFolder(root, folder, { pid = process.pid, tries = 5 } = {}) {
+  for (let triesLeft = tries - 1; ; triesLeft -= 1) {
+    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]);
+    if (held.stale) tryGit(root, ['worktree', 'unlock', folder]);
+    const locked = 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 };
+    const said = whoEndedUpInTheLock({ pid, locked, after: record(root, folder)?.lock, triesLeft });
+    if (!said.again) return said;
+  }
 }
 
 /**
@@ -266,13 +505,33 @@ export function acquireTaskFolder(root, folder, { pid = process.pid } = {}) {
  * 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 } = {}) {
+export function ensureTaskFolder(dir, id, { pid = process.pid, dependencies = true, again = false } = {}) {
   const name = safeTaskName(id);
-  const root = repoRoot(dir);
+  const root = repoRoot(dir) ?? startRepository(dir);
   if (!root) return null;
+  firstCommitIfNone(root);
   const folder = taskFolderPath(root, name);
   const branch = taskBranch(name);
-  const refused = (held) => ({ taken: false, reason: held.reason, heldBy: held.heldBy ?? null, path: null });
+  // A LOCK GIT WOULD NOT WRITE IS NOT A REFUSAL. Nobody else has the folder,
+  // and every reason above names somebody or something; this one names this
+  // machine, so it leaves by the road failures leave by, which puts git's words
+  // on the row (`_couldNotGetAFolder` in main/supervisor.mjs).
+  const refused = (held) => {
+    if (held.reason === 'unlockable') throw Error(`Could not take the folder for ${name}: ${held.detail}`);
+    return { taken: false, reason: held.reason, heldBy: held.heldBy ?? null, path: null };
+  };
+
+  // SOMEBODY ELSE FINISHED THE FOLDER WHILE WE WERE MAKING IT, which is not the
+  // same thing as somebody still making it (w-36c51443df). Measured 2026-10-17,
+  // six processes on one id on a busy machine: a loser can get all the way to
+  // its `worktree move` and find the winner has already moved its own copy into
+  // place, so git refuses with a fatal about staging and nobody is building
+  // anything any more. The answer is the road at the top of this function --
+  // the folder is there, ask to hold it -- so the three exits below take it
+  // rather than inventing a word for a race that is already over. Asked once:
+  // a second failure is not a race.
+  const somebodyFinishedIt = () => !again && fs.existsSync(folder) && !!record(root, folder);
+  const askAgain = () => ensureTaskFolder(dir, id, { pid, dependencies, again: true });
 
   if (fs.existsSync(folder) && record(root, folder)) {
     const held = acquireTaskFolder(root, folder, { pid });
@@ -289,12 +548,15 @@ export function ensureTaskFolder(dir, id, { pid = process.pid, dependencies = tr
   // 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.
+  // EMPTY one excepted, or one holding only LEFTOVER_MARKERS, since there is
+  // nothing there to lose and a stray one 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 }); }
+    const left = tryRead(folder);
+    if (!left.every((name) => LEFTOVER_MARKERS.has(name) && isPlainFile(path.join(folder, name)))) return refused({ reason: 'in-the-way', heldBy: null });
+    try {
+      for (const name of left) fs.rmSync(path.join(folder, name));
+      fs.rmdirSync(folder);
+    } catch { return refused({ reason: 'in-the-way', heldBy: null }); }
   }
 
   // A registration whose directory somebody deleted by hand would refuse the
@@ -344,7 +606,28 @@ export function ensureTaskFolder(dir, id, { pid = process.pid, dependencies = tr
     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 (!add.ok) {
+      // SOMEBODY GOT HERE FIRST, AND THAT IS A REFUSAL RATHER THAN A FAILURE
+      // (w-36c51443df). `clearUnfinished` above answers `building` only when
+      // staging is already REGISTERED AND LOCKED, and the window this lands in
+      // is narrower than that: between its "nothing there" and this add, another
+      // process created the directory. Measured 2026-10-09, six processes on one
+      // id: one won and five threw `fatal: '<staging>' already exists`, so the
+      // documented `building` reason could not fire in the one case it was
+      // written for.
+      //
+      // The row waited either way -- `_couldNotGetAFolder` sees the throw and
+      // says so in plain words -- so this is about what she reads, not about
+      // safety. "Another session is building this folder" is both true and
+      // something to act on; a git fatal about a dot-prefixed path is neither.
+      //
+      // AND SOMETIMES THE WINNER HAS ALREADY FINISHED, which `somebodyFinishedIt`
+      // above explains: the add was refused because the branch is checked out in
+      // the folder the winner has just made.
+      if (somebodyFinishedIt()) return askAgain();
+      if (somebodyIsBuilding(add.out)) return refused({ reason: 'building', heldBy: null });
+      throw Error(`Could not make a folder for ${name}: ${add.out}`);
+    }
   }
 
   // AND THE LOCAL FILES THE REPOSITORY ASKS FOR, THE SAME WAY WHICHEVER PATH RAN.
@@ -380,12 +663,22 @@ export function ensureTaskFolder(dir, id, { pid = process.pid, dependencies = tr
   // handed over. The destination was checked above and is checked again here,
   // since the whole build has run since.
   if (fs.existsSync(folder)) {
+    const finished = somebodyFinishedIt();
     clearUnfinished(root, staging, pid);
+    // A registered worktree at that path is another session's finished work, not
+    // a stray directory in the way, and it has a better answer than `in-the-way`.
+    if (finished) return askAgain();
     return refused({ reason: 'in-the-way', heldBy: null });
   }
   const moved = tryGit(root, ['worktree', 'move', '--force', '--force', staging, folder]);
   if (!moved.ok) {
     clearUnfinished(root, staging, pid);
+    // THE EXIT THE RACE ACTUALLY TAKES, found 2026-10-17 and missed on 2026-10-09
+    // because one run of a race is not a measurement of it: two sessions can both
+    // build the same staging copy, and the one that moves second finds the path
+    // gone -- `fatal: '<staging>' is not a working tree`.
+    if (somebodyFinishedIt()) return askAgain();
+    if (somebodyIsBuilding(moved.out)) return refused({ reason: 'building', heldBy: null });
     throw Error(`Could not make a folder for ${name}: ${moved.out}`);
   }
 
@@ -401,10 +694,23 @@ export function ensureTaskFolder(dir, id, { pid = process.pid, dependencies = tr
  * 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.
+ *
+ * AN ADD THAT SAYS IT FAILED MAY HAVE MADE THE FOLDER ANYWAY (2026-10-15). git
+ * runs the repository's post-checkout hook after the worktree is made and
+ * hands back the hook's exit as its own, and git-lfs's hook exits 1 on a
+ * machine without git-lfs. Read as a failure, the retry below was refused
+ * because the first add had already made the branch, and every task in that
+ * repository went without a folder. A checkout that itself fails is undone by
+ * git and leaves nothing registered, so a registered folder with a commit in
+ * it is one the hook complained about after the fact, and it is ours.
  */
 function addOwned(root, folder, rest, pid) {
   const owned = tryGit(root, ['worktree', 'add', '--lock', '--reason', lockReason(pid), ...rest]);
   if (owned.ok) return owned;
+  if (record(root, folder) && tryGit(folder, ['rev-parse', '--verify', '-q', 'HEAD']).ok) {
+    if (record(root, folder)?.lock === undefined) tryGit(root, ['worktree', 'lock', '--reason', lockReason(pid), folder]);
+    return { ok: true, out: owned.out };
+  }
   const added = tryGit(root, ['worktree', 'add', ...rest]);
   if (added.ok) tryGit(root, ['worktree', 'lock', '--reason', lockReason(pid), folder]);
   return added;
@@ -597,6 +903,15 @@ function ownFolder(root, name, given) {
   return real(given) === mine ? mine : null;
 }
 
+/**
+ * AND STILL ON THE TASK'S OWN BRANCH, asked right before anything is committed
+ * or removed. The path alone was not proof (GitHub issue #43: another tool's
+ * worktree sat at the same path), and a folder an agent moved off its branch
+ * would be committed onto the wrong one, or, on no branch at all, onto nothing
+ * and then deleted.
+ */
+const onItsOwnBranch = (root, folder, name) => record(root, folder)?.branch === taskBranch(name);
+
 /**
  * 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
@@ -610,6 +925,7 @@ export function releaseTaskFolder(dir, id, { pid = process.pid, path: given = nu
   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' };
+  if (!onItsOwnBranch(root, folder, name)) return { removed: false, reason: 'not-ours', 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
@@ -624,11 +940,89 @@ export function releaseTaskFolder(dir, id, { pid = process.pid, path: given = nu
   tryGit(root, ['worktree', 'unlock', folder]);
   // No --force: git refuses a second time if anything is uncommitted, which is
   // the belt under this braces.
-  const removed = tryGit(root, ['worktree', 'remove', folder]);
+  const removed = removeWorktree(root, folder);
   if (!removed.ok) return { removed: false, reason: 'refused', path: folder, detail: removed.out };
   return { removed: true, reason: 'merged', path: folder };
 }
 
+/**
+ * `git worktree remove`, AND A FOLDER HOLDING SUBMODULES TOO, WHEN THAT LOSES
+ * NOTHING (2026-10-15).
+ *
+ * git refuses to remove any worktree with a submodule filled in, clean or not:
+ * "working trees containing submodules cannot be moved or removed". A task in a
+ * repository with submodules starts with them empty, so an agent's first act is
+ * `git submodule update --init`, and from then on park and release were refused
+ * on every sweep and that folder was never reclaimed. Emptying the submodules
+ * first does not help: git still refuses while their repositories live on
+ * under the worktree's own `modules`.
+ *
+ * The refusal guards one real thing. Those repositories are the only copy of
+ * anything committed inside a submodule and not pushed, and `--force` deletes
+ * them. So it is forced only once that is provably nothing: no file anywhere in
+ * the folder or its submodules uncommitted, no submodule whose repository sits
+ * inside its own directory where this cannot look, and every commit in every
+ * submodule repository already on one of its remotes. Anything else stays
+ * refused, kept and reported as before.
+ */
+function removeWorktree(root, folder) {
+  const removed = tryGit(root, ['worktree', 'remove', folder]);
+  if (removed.ok || !/submodules/.test(removed.out)) return removed;
+  if (!submodulesHoldNothingOfTheirOwn(folder)) return removed;
+  return tryGit(root, ['worktree', 'remove', '--force', folder]);
+}
+
+function submodulesHoldNothingOfTheirOwn(folder) {
+  try {
+    const status = tryGit(folder, ['status', '--porcelain', '--ignore-submodules=none']);
+    if (!status.ok || status.out !== '') return false;
+    if (!everySubmoduleKeepsItsRepositoryOutside(folder)) return false;
+    const gitDir = tryGit(folder, ['rev-parse', '--absolute-git-dir']);
+    if (!gitDir.ok) return false;
+    return repositoriesUnder(path.join(gitDir.out, 'modules')).every((repo) => {
+      const own = tryGit(repo, ['--git-dir', repo, 'rev-list', '-n', '1', '--all', '--not', '--remotes']);
+      return own.ok && own.out === '';
+    });
+  } catch { return false; }
+}
+
+/**
+ * A submodule added from a repository already in place keeps that repository
+ * in its own `.git` directory rather than under `modules`, and a forced removal
+ * deletes it with the files. Asked of every level, since a submodule can hold
+ * its own.
+ */
+function everySubmoduleKeepsItsRepositoryOutside(at) {
+  const staged = tryGit(at, ['ls-files', '-s']);
+  if (!staged.ok) return false;
+  for (const line of staged.out.split('\n')) {
+    if (!line.startsWith('160000 ')) continue;
+    const inner = path.join(at, line.slice(line.indexOf('\t') + 1));
+    const dotGit = path.join(inner, '.git');
+    if (!fs.existsSync(dotGit)) continue;
+    if (fs.lstatSync(dotGit).isDirectory() || !everySubmoduleKeepsItsRepositoryOutside(inner)) return false;
+  }
+  return true;
+}
+
+/** Every repository in a `modules` directory, nested ones included. Throws on one it cannot read. */
+function repositoriesUnder(dir) {
+  if (!fs.existsSync(dir)) return [];
+  const found = [];
+  const walk = (at) => {
+    if (fs.existsSync(path.join(at, 'HEAD')) && fs.existsSync(path.join(at, 'objects'))) {
+      found.push(at);
+      if (fs.existsSync(path.join(at, 'modules'))) walk(path.join(at, 'modules'));
+      return;
+    }
+    for (const entry of fs.readdirSync(at, { withFileTypes: true })) {
+      if (entry.isDirectory()) walk(path.join(at, entry.name));
+    }
+  };
+  walk(dir);
+  return found;
+}
+
 /** The subject line that marks a commit as work parked rather than finished. */
 export const PARKED = 'Parked when the task was closed';
 
@@ -675,6 +1069,7 @@ export function parkTaskFolder(dir, id, { pid = process.pid, path: given = null
   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' };
+  if (!onItsOwnBranch(root, folder, name)) return { parked: false, reason: 'not-ours', path: folder };
 
   const owner = holder(root, folder, pid);
   if (!owner.ok) return { parked: false, reason: owner.reason, heldBy: owner.heldBy, path: folder };
@@ -699,18 +1094,19 @@ export function parkTaskFolder(dir, id, { pid = process.pid, path: given = null
     // 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 as = asTheApp(folder);
+    tryGit(folder, [...as, '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 tree = tryGit(folder, ['commit', '--no-verify', '--allow-empty', '-q', '-m', PARKED]);
+    const tree = tryGit(folder, [...as, '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';
   }
 
   tryGit(root, ['worktree', 'unlock', folder]);
-  const removed = tryGit(root, ['worktree', 'remove', folder]);
+  const removed = removeWorktree(root, folder);
   if (!removed.ok) return { parked: false, reason: 'refused', path: folder, detail: removed.out };
   return { parked: true, kept, path: folder };
 }
@@ -766,9 +1162,12 @@ export function restoreTaskFolder(dir, id, { pid = process.pid } = {}) {
  * 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
+ * `ours` IS PROOF BY LOCATION AND BRANCH. The location alone is not enough:
+ * Claude Code's desktop app makes its worktrees at that same
+ * `<primary>/.claude/worktrees/<name>`, on `claude/<name>`, and the sweep parked
+ * and removed three of them with live sessions in them (GitHub issue #43). So a
+ * folder there is ours only when it is also on a branch `taskBranch` names; one
+ * on any other branch, or on none, is a stray. 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).
@@ -808,7 +1207,8 @@ export function inventoryWorktrees(dir) {
       // 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),
+        && path.dirname(at) === home && couldBeATaskName(name)
+        && String(w.branch ?? '').startsWith(BRANCH_PREFIX),
     };
   });
 }