@ajaykumarnpm/talea 0.1.0 → 0.2.0

package/README.md

@@ -79,12 +79,24 @@ A move keeps everything: branches, stashes, the reflog, your uncommitted
 changes. A re-clone throws all of it away, which is why this tool does not do
 one.
 
+**Worktrees come too.** The sibling `<repo>-worktrees/` folder moves alongside
+the repo, and every worktree is re-linked afterwards — the ones that moved and
+the ones that did not. A worktree is never mistaken for a second copy of the
+repo, even though git reports the same `origin` for both.
+
 ```sh
 talea adopt                      # show what would move, change nothing
 talea adopt --from ~/Desktop     # look there too; the folder is remembered
 talea adopt --apply              # do it
 ```
 
+Matching is on the remote URL. When only the *name* matches — a fork, a mirror,
+or a directory that merely shares a name — it is listed and left alone; `--loose`
+or `-r <repo>` includes it once you have looked. That guard is not theoretical:
+an FVM Flutter SDK cache reports `origin` as `flutter/flutter`, which name-matches
+a personal `flutter` fork, and moving it would break every Flutter project on the
+machine.
+
 If the same repo turns up twice, the copy at the catalogue path wins and the
 other moves into `.talea-duplicates/` with everything in it. **Nothing is ever
 deleted.** Clearing that folder is your call.
@@ -95,6 +107,18 @@ repo that moves and loses its history has not really been helped.
 
 ---
 
+## When another tool owns a checkout
+
+Mark it in the catalogue and talea leaves it completely alone:
+
+```json
+{ "name": "some-repo", "owner": "someone", "ignore": true }
+```
+
+Without this, two tools that both organise repositories will each drag the same
+checkout back to where it thinks it belongs, on every run. Use it for repos
+inside another workspace manager's tree, vendored checkouts, and SDK caches.
+
 ## What travels, and what does not
 
 | | Where it lives | Shared |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ajaykumarnpm/talea",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "One folder structure for every machine. Clone, adopt and sync your GitHub repos from a manifest you own.",
   "type": "module",
   "bin": {

package/src/adopt.js

@@ -142,6 +142,23 @@ export function catalogueUrls(manifest, repo) {
   return urls;
 }
 
+/**
+ * Is this directory a linked worktree rather than a checkout of its own?
+ *
+ * A worktree's `.git` is a file holding a pointer, where a real checkout has a
+ * directory. The distinction matters because a worktree reports the same
+ * `origin` as the repo it belongs to, so by remote alone it is indistinguishable
+ * from a second clone — and treating one as a stray copy is how you rename it
+ * out from under git and unroot every commit in it.
+ */
+export function isLinkedWorktree(dir) {
+  try {
+    return lstatSync(path.join(dir, '.git')).isFile();
+  } catch {
+    return false;
+  }
+}
+
 /**
  * Which catalogue repo does this remote belong to?
  *
@@ -250,16 +267,6 @@ async function moveBlockers(dir) {
     return 'no .git found';
   }
 
-  const { code, stdout } = await git(['worktree', 'list', '--porcelain'], { cwd: dir });
-  if (code === 0) {
-    const outside = strandedWorktrees(dir, stdout);
-    if (outside.length) {
-      return (
-        `${outside.length} extra worktree(s) registered elsewhere — their absolute ` +
-        `paths would break: ${outside.join(', ')}`
-      );
-    }
-  }
   return null;
 }
 
@@ -292,37 +299,69 @@ export function canonical(p) {
 }
 
 /**
- * Worktrees a move would actually strand.
- *
- * Two kinds are not blockers, and treating them as such refused a move that
- * was perfectly safe:
+ * Every linked worktree of this repo, as git currently records it.
  *
- *  - `prunable` — git already knows the directory is gone, so a stale
- *    registration has no path left to break.
- *  - one living *inside* the repo (`.claude/worktrees/x`) — it travels with
- *    the rename, and `git worktree repair` re-links it afterwards.
+ * `prunable` ones are skipped: git already knows the directory is gone, so
+ * there is no path left to repair. `--porcelain` emits a blank-line-separated
+ * block per worktree, the first being the main checkout — which is the repo
+ * being moved, not a link into it.
  *
- * What is left is a worktree somewhere else on disk, which really would be
- * orphaned. `--porcelain` emits a blank-line-separated block per worktree,
- * the first being the main checkout.
+ * This used to return only the worktrees *outside* the repo, and a move was
+ * refused when there were any. That was wrong: an external worktree does not
+ * move, so nothing about it breaks except the pointer in its own `.git` file,
+ * and `git worktree repair` exists to rewrite exactly that. Refusing meant a
+ * developer who uses worktrees at all could never have their repos organised —
+ * and it cascaded, because a refused winner leaves every duplicate of it
+ * refused too.
  */
-export function strandedWorktrees(dir, porcelain) {
-  const base = canonical(dir);
-  const inside = (p) => {
-    const rel = path.relative(base, canonical(p));
-    return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
-  };
-
+export function linkedWorktrees(porcelain) {
   return String(porcelain)
     .split(/\r?\n\s*\r?\n/)
     .map((block) => lines(block))
     .filter((block) => block.length && block[0].startsWith('worktree '))
-    .slice(1) // the main checkout is the thing being moved, not a blocker
+    .slice(1) // the main checkout is the thing being moved, not a link into it
     .filter((block) => !block.some((l) => l === 'prunable' || l.startsWith('prunable ')))
-    .map((block) => block[0].slice('worktree '.length))
-    .filter((p) => !inside(p));
+    .map((block) => block[0].slice('worktree '.length));
 }
 
+/**
+ * Where a worktree ends up once the repo has moved.
+ *
+ * Three cases, and the whole correctness of the repair is getting them right:
+ *
+ *  - inside the repo (`.claude/worktrees/x`) — travelled with the rename.
+ *  - inside the sibling `<repo>-worktrees/` folder, when that folder was moved
+ *    alongside — travelled too, to the new sibling.
+ *  - anywhere else — did not move at all, and must be repaired where it sits.
+ */
+export function remapWorktree(p, { from, to, siblings }) {
+  const within = (base) => {
+    const rel = path.relative(canonical(base), canonical(p));
+    return rel && !rel.startsWith('..') && !path.isAbsolute(rel) ? rel : null;
+  };
+
+  const nested = within(from);
+  if (nested) return path.join(to, nested);
+
+  if (siblings) {
+    const moved = within(siblings.from);
+    if (moved) return path.join(siblings.to, moved);
+  }
+
+  return p;
+}
+
+/**
+ * The sibling folder worktrees are conventionally kept in.
+ *
+ * `<repo>-worktrees/`, derived from the repo's own path rather than stored
+ * anywhere — which is why it has to move when the repo does. Leave it behind
+ * and the tooling that creates worktrees starts using a new empty folder next
+ * to the moved repo while every existing worktree sits beside the old location.
+ * Both halves keep working; the developer now has two.
+ */
+export const siblingWorktreeDir = (repoPath) => `${repoPath}-worktrees`;
+
 /**
  * What a second copy holds that the copy being kept does not.
  *
@@ -411,6 +450,14 @@ export async function planAdoptions(manifest, root, repos, candidates) {
   for (const { dir, originUrl } of candidates) {
     const match = matchRepo(manifest, repos, originUrl);
     if (!match) continue;
+
+    // A linked worktree shares its repo's origin, so it arrives here looking
+    // exactly like a second clone. It is not one — it is part of the repo, and
+    // it travels when the repo moves (see relocateWorktrees). Reporting one as
+    // a stray copy produced a refusal line per worktree, which for a developer
+    // who uses them buried the real findings under fifteen lines of noise.
+    if (isLinkedWorktree(dir)) continue;
+
     const key = match.repo.name;
     if (!byRepo.has(key)) byRepo.set(key, { repo: match.repo, copies: [] });
     byRepo.get(key).copies.push({ dir, originUrl, confidence: match.confidence });
@@ -506,38 +553,83 @@ export async function planAdoptions(manifest, root, repos, candidates) {
  * moved aside, and the developer removes the duplicates area themselves.
  */
 /**
- * Re-link worktrees that lived inside the repo and moved with it.
+ * What git records about this repo's worktrees, read BEFORE it moves.
  *
- * Every link between a repo and its worktrees is an absolute path to where the
- * repo used to be, and `git worktree repair` with no arguments cannot help:
- * it looks for each worktree at its recorded path, which is exactly the path
- * that no longer exists. Handing it the new paths is what the flag is for.
+ * The ordering is load-bearing. Once the repo has moved, every worktree that
+ * travelled with it is reported `prunable` — git looks for it at its recorded
+ * location, which is the path that just stopped existing — and a prunable
+ * entry is indistinguishable from a genuinely dead one. Read after the move
+ * and the worktrees that most need repairing are exactly the ones filtered out.
  */
-function repairNestedWorktrees(from, to) {
+export function readWorktrees(dir) {
   const listed = spawnSync('git', ['worktree', 'list', '--porcelain'], {
-    cwd: to,
+    cwd: dir,
     encoding: 'utf8',
   });
-  if (listed.status !== 0) return;
+  return listed.status === 0 ? linkedWorktrees(listed.stdout) : [];
+}
+
+/**
+ * Bring a repo's worktrees with it, then re-link every one of them.
+ *
+ * Every link between a repo and a worktree is an absolute path to where the
+ * repo used to be, so a rename breaks all of them at once. `git worktree
+ * repair` with no arguments cannot help: it looks for each worktree at its
+ * recorded path, which is exactly the path that no longer exists. Handing it
+ * the new paths is what the argument form is for.
+ *
+ * The sibling `<repo>-worktrees/` folder moves too. That location is derived
+ * from the repo's own path at the moment a worktree is created, never stored,
+ * so leaving it behind does not break anything — it silently splits the
+ * workflow in half instead, new worktrees appearing next to the moved repo
+ * while every existing one stays beside the old location. Splitting something
+ * in two and reporting success is worse than refusing.
+ *
+ * Nothing is deleted and nothing is overwritten: an occupied destination means
+ * the folder stays where it is, and the worktrees in it are repaired in place.
+ */
+function relocateWorktrees(from, to, recorded) {
+  if (!recorded.length) return { repaired: [], siblings: null, stale: 0 };
+
+  // The sibling folder moves only if it exists, is going somewhere new, and
+  // that somewhere is free. Anything else and the worktrees stay put — still
+  // correct, just not tidied.
+  let siblings = null;
+  const fromSiblings = siblingWorktreeDir(from);
+  const toSiblings = siblingWorktreeDir(to);
+  if (
+    existsSync(fromSiblings) &&
+    !samePath(fromSiblings, toSiblings) &&
+    !existsSync(toSiblings)
+  ) {
+    try {
+      mkdirSync(path.dirname(toSiblings), { recursive: true });
+      renameSync(fromSiblings, toSiblings);
+      siblings = { from: fromSiblings, to: toSiblings };
+    } catch {
+      // A cross-device sibling folder, or one being written to. The repo has
+      // already moved and is fine; the worktrees are repaired where they are.
+    }
+  }
 
-  const moved = lines(listed.stdout)
-    .filter((l) => l.startsWith('worktree '))
-    .map((l) => l.slice('worktree '.length))
-    .map((p) => path.relative(canonical(from), canonical(p)))
-    .filter((rel) => rel && !rel.startsWith('..') && !path.isAbsolute(rel))
-    .map((rel) => path.join(to, rel));
+  const now = recorded
+    .map((p) => remapWorktree(p, { from, to, siblings }))
+    .filter((p) => existsSync(p));
 
-  if (moved.length) {
-    spawnSync('git', ['worktree', 'repair', ...moved], { cwd: to, stdio: 'ignore' });
+  if (now.length) {
+    spawnSync('git', ['worktree', 'repair', ...now], { cwd: to, stdio: 'ignore' });
   }
+  return { repaired: now, siblings, stale: recorded.length - now.length };
 }
 
 export function executeMove(plan) {
   try {
     mkdirSync(path.dirname(plan.to), { recursive: true });
+    // Read before the rename: see readWorktrees.
+    const recorded = readWorktrees(plan.from);
     renameSync(plan.from, plan.to);
-    repairNestedWorktrees(plan.from, plan.to);
-    return { ok: true, to: plan.to };
+    const worktrees = relocateWorktrees(plan.from, plan.to, recorded);
+    return { ok: true, to: plan.to, worktrees };
   } catch (err) {
     if (err.code === 'EXDEV') {
       const cmd = process.platform === 'win32' ? 'move' : 'mv';

package/src/cli.js

@@ -70,6 +70,7 @@ const OPTIONS = {
   gist: { type: 'string' },
   apply: { type: 'boolean', default: false },
   'fix-paths': { type: 'boolean', default: false },
+  loose: { type: 'boolean', default: false },
   // parseArgs has no --no-x negation, so the negative flags are declared
   // explicitly and inverted below.
   'no-adopt': { type: 'boolean', default: false },

package/src/commands/adopt.js

@@ -4,7 +4,7 @@ import path from 'node:path';
 
 import { expandHome, loadState, saveState } from '../config.js';
 import { c, fail, glyph, heading, icon, info, ok, plain, skip, summary, warn } from '../log.js';
-import { requireCatalogue, requireWorkspace, selectRepos } from '../workspace.js';
+import { adoptable, requireCatalogue, requireWorkspace, selectRepos } from '../workspace.js';
 import {
   DUPLICATES_DIR,
   claudeMaybeRunning,
@@ -34,9 +34,13 @@ called ${c.dim('~/tmp/clone2')} is still recognised as the repo it holds. A matc
 ${c.bold('moved')}, never re-cloned — the move keeps every branch, stash, reflog entry
 and uncommitted change exactly as it is.
 
-A repo that cannot be moved safely (a linked worktree, extra worktrees, an
-occupied destination, another filesystem) is left alone and the reason is
-printed.
+${c.bold('Worktrees come too.')} The sibling ${c.dim('<repo>-worktrees/')} folder moves alongside the
+repo, and every worktree — there, nested inside the repo, or anywhere else on
+disk — is re-linked afterwards. A worktree that does not move is repaired where
+it sits.
+
+A repo that cannot be moved safely (it is itself a linked worktree, an occupied
+destination, another filesystem) is left alone and the reason is printed.
 
 When the same repo is found twice, the copy at the catalogue path wins and the
 other moves into ${c.bold(DUPLICATES_DIR)}/ — never deleted, never left outside the tree.
@@ -52,6 +56,10 @@ Options
   -r, --repo <names>    restrict to repos
       --from <path>     extra folder to search (repeatable, remembered)
       --apply           perform the moves (default is a dry run)
+      --loose           also move repos matched by name when the remote differs
+
+A repo marked ${c.dim('"ignore": true')} in the catalogue is never touched by any command —
+that is how you tell talea another tool owns a checkout.
       --fix-paths       re-repair config for repos already adopted, moving nothing
   -j, --jobs <n>        parallel git calls (default 8)
 `;
@@ -97,6 +105,23 @@ export async function applyMoves(root, moves, parks = [], manifest) {
     ok(
       `${c.bold(plan.repo.name)} ${c.dim(shorten(plan.from))} ${icon.arrow} ${c.dim(path.relative(root, plan.to))}`,
     );
+
+    // Said out loud, always. A worktree folder moving is a second directory
+    // relocating on the developer's disk, and the one thing worse than not
+    // moving it is moving it without saying so.
+    const wt = res.worktrees;
+    if (wt?.siblings) {
+      plain(
+        `    ${c.dim(glyph.pending)} worktrees ${c.dim(shorten(wt.siblings.from))} ${icon.arrow} ${c.dim(path.relative(root, wt.siblings.to))}`,
+      );
+    }
+    if (wt?.repaired?.length) {
+      plain(
+        `    ${c.dim(glyph.pending)} ${wt.repaired.length} worktree${wt.repaired.length > 1 ? 's' : ''} re-linked` +
+          (wt.stale ? c.yellow(` (${wt.stale} unreachable, left registered)`) : ''),
+      );
+    }
+
     const repairs = repairPaths(root, plan);
     results.push({ plan, ok: true, repairs });
   }
@@ -312,7 +337,8 @@ export async function run(opts) {
 
   // The whole catalogue, not this machine's selection: a stray checkout is
   // worth moving into place whether or not this machine had signed up for it.
-  const repos = selectRepos(manifest, opts, manifest.repos);
+  // Minus anything marked `ignore` — see `adoptable`.
+  const repos = selectRepos(manifest, opts, adoptable(manifest));
 
   const extra = parseFromPaths(opts.from);
 
@@ -344,6 +370,29 @@ export async function run(opts) {
     return;
   }
 
+  // A name-only match means the remote host is not one the catalogue lists:
+  // the repo NAME matched and the URL did not. That is usually a fork or a
+  // mirror and usually right — and when it is wrong it is very wrong. An FVM
+  // Flutter SDK cache at ~/SDK/FVM/cache.git has origin flutter/flutter, which
+  // name-matches a personal `flutter` fork, and moving it breaks every Flutter
+  // project on the machine.
+  //
+  // `clone` and `sync` already refuse to act on these unattended. `adopt
+  // --apply` used to move them after printing a warning nobody had to answer,
+  // which made the warning decorative. Now they need saying so: --loose, or
+  // naming the repo with -r, which is itself an explicit instruction.
+  const named = Boolean(opts.repo);
+  const loose = Boolean(opts.loose) || named;
+  //
+  // Parking is a move too, and the FVM case was a PARK, not a move: the
+  // catalogue path was empty, so the SDK cache was second-in-line and headed
+  // for .talea-duplicates/. Gating only `moves` would have left the exact
+  // directory this guard exists for still being relocated.
+  const exact = (p) => p.confidence === 'exact';
+  const unsure = [...moves, ...parks].filter((p) => !exact(p));
+  const willMove = loose ? moves : moves.filter(exact);
+  const willPark = loose ? parks : parks.filter(exact);
+
   if (moves.length && !opts.apply) {
     plain('');
     for (const p of moves) {
@@ -354,11 +403,18 @@ export async function run(opts) {
           `      to    ${c.dim(path.relative(root, p.to))}`,
       );
     }
-    if (moves.some((p) => p.confidence === 'name')) {
+    if (unsure.length) {
       plain('');
       warn(
-        `${c.yellow('~')} matched on repo name only — the remote host is not one the catalogue lists.\n` +
-          `  Check those remotes before applying.`,
+        `${c.yellow('~')} ${unsure.length} matched on repo name only — the remote host is not one the\n` +
+          `  catalogue lists. Check those remotes: a directory that merely shares a name\n` +
+          `  with one of your repos is not one of your repos.`,
+      );
+      plain(
+        c.dim(
+          `  --apply leaves them alone. Add ${c.bold('--loose')} to include them, or name one\n` +
+            `  with ${c.bold('-r <repo>')} once you have checked it.`,
+        ),
       );
     }
   }
@@ -390,8 +446,11 @@ export async function run(opts) {
 
   if (!opts.apply) {
     const bits = [];
-    if (moves.length) bits.push(`move ${moves.length} into place`);
-    if (parks.length) bits.push(`park ${parks.length} second cop${parks.length === 1 ? 'y' : 'ies'}`);
+    if (willMove.length) bits.push(`move ${willMove.length} into place`);
+    if (willPark.length) bits.push(`park ${willPark.length} second cop${willPark.length === 1 ? 'y' : 'ies'}`);
+    if (unsure.length && !loose) {
+      bits.push(`${c.yellow(`leave ${unsure.length} name-only match${unsure.length === 1 ? '' : 'es'} alone`)}`);
+    }
     plain(`\n${c.dim(bits.length ? `Re-run with --apply to ${bits.join(' and ')}.` : 'Nothing to apply.')}`);
     return;
   }
@@ -400,13 +459,25 @@ export async function run(opts) {
     saveState(root, { ...state, scanPaths: [...new Set([...remembered, ...extra])] });
   }
 
+  if (unsure.length && !loose) {
+    plain('');
+    for (const p of unsure) {
+      warn(
+        `${c.bold(p.repo.name)} left alone — matched on name only, not on remote\n` +
+          `    ${c.dim(shorten(p.from))}\n` +
+          `    ${c.dim(p.originUrl ?? 'no origin')}`,
+      );
+    }
+    plain(c.dim('  Check the remote, then re-run with --loose or -r to include it.'));
+  }
+
   plain('');
-  const applied = await applyMoves(root, moves, parks, manifest);
+  const applied = await applyMoves(root, willMove, willPark, manifest);
   const okCount = applied.results.filter((r) => r.ok).length;
   summary({
     ok: okCount + applied.parked.length,
     skipped: inPlace.length,
-    failed: applied.results.length - okCount + (parks.length - applied.parked.length),
+    failed: applied.results.length - okCount + (willPark.length - applied.parked.length),
     okLabel: 'relocated',
   });
 

package/src/commands/clone.js

@@ -7,7 +7,7 @@ import { clone, defaultJobs, isMissingRemote, pooled } from '../git.js';
 import { board } from '../live.js';
 import { c, heading, icon, ok, plain, summary, warn } from '../log.js';
 import { chooseRepos } from '../select.js';
-import { requireCatalogue, requireWorkspace, selectRepos, withPaths } from '../workspace.js';
+import { adoptable, requireCatalogue, requireWorkspace, selectRepos, withPaths } from '../workspace.js';
 import { applyMoves, parseFromPaths, planFor } from './adopt.js';
 
 export const help = `
@@ -64,7 +64,14 @@ export async function adoptInPlace({ manifest, root, state, repos, opts }) {
     saveState(root, { ...state, scanPaths: [...new Set([...(state.scanPaths ?? []), ...extra])] });
   }
 
-  const { moves, parks, refused } = await planFor({ manifest, root, repos, scanRoots, jobs: opts.jobs });
+  const ours = repos.filter((r) => !r.ignore);
+  const { moves, parks, refused } = await planFor({
+    manifest,
+    root,
+    repos: ours,
+    scanRoots,
+    jobs: opts.jobs,
+  });
 
   // A name-only match means the remote host is not one the catalogue lists, so
   // it is probably right but not certainly. This runs unattended, so it only

package/src/commands/discover.js

@@ -21,7 +21,7 @@ Options
       --apply            write the file (default prints what would change)
 
 ${c.bold('What is preserved')} — a repo already in the catalogue keeps its ${c.dim('default')},
-${c.dim('group')} and ${c.dim('dir')}. Discovery refreshes the facts GitHub owns; the choices are
+${c.dim('group')}, ${c.dim('dir')} and ${c.dim('ignore')}. Discovery refreshes the facts GitHub owns; the choices are
 yours and are never overwritten.
 
 Auth comes from ${c.dim('gh auth token')}, then ${c.dim('GITHUB_TOKEN')}, then nothing — and nothing is
@@ -85,6 +85,7 @@ export function merge(existing, found) {
       ...(prior?.group !== undefined ? { group: prior.group } : {}),
       ...(prior?.dir !== undefined ? { dir: prior.dir } : {}),
       ...(prior?.url !== undefined ? { url: prior.url } : {}),
+      ...(prior?.ignore !== undefined ? { ignore: prior.ignore } : {}),
     });
   }
 

package/src/commands/init.js

@@ -1,25 +1,29 @@
 import { existsSync, mkdirSync } from 'node:fs';
 import path from 'node:path';
 
+import os from 'node:os';
+
 import {
   STATE_FILE,
   expandHome,
+  findWorkspace,
   groupDir,
   loadManifest,
   loadState,
   repoGroup,
   saveState,
 } from '../config.js';
+import { samePath } from '../adopt.js';
 import { machineRepos } from '../workspace.js';
-import { c, context, heading, info, ok, plain, skip, warn } from '../log.js';
+import { c, context, fail, heading, info, ok, plain, skip, warn } from '../log.js';
 import { run as discover } from './discover.js';
 import { run as sync } from './sync.js';
 
 export const help = `
 ${c.bold('talea init')} — set this machine up
 
-  ${c.dim('talea init')}                      use the current folder as the workspace
-  ${c.dim('talea init ~/Workspace')}          use that folder instead
+  ${c.dim('talea init')}                      set up ~/Workspace
+  ${c.dim('talea init ~/code')}               use that folder as the root instead
   ${c.dim('talea init --no-clone')}           write the config, clone later
 
 Creates the workspace, records this machine's preferences in ${STATE_FILE}, asks
@@ -41,8 +45,53 @@ ${c.bold('On your second machine')}, pull the catalogue first:
   ${c.dim('talea init ~/Workspace')}
 `;
 
+/**
+ * Where the workspace goes.
+ *
+ * The default is `~/Workspace`, never the current directory. `init` run from
+ * the home folder used to make HOME itself the root, which puts owner folders
+ * directly in the home directory and points every later scan at three levels of
+ * $HOME. It reads as working, so nobody notices until the tree is already
+ * spread out.
+ *
+ * The name comes from the catalogue, so a team that keeps its checkouts under
+ * `src/` or `code/` changes one field rather than telling everyone a flag.
+ */
+export function workspaceTarget(positional, manifest) {
+  if (positional) return path.resolve(expandHome(positional));
+  return path.join(os.homedir(), manifest?.workspace || 'Workspace');
+}
+
 export async function run(opts, positionals = []) {
-  const target = path.resolve(expandHome(positionals[0] ?? process.cwd()));
+  const target = workspaceTarget(positionals[0], loadManifest(null));
+
+  // The home directory is not a workspace. Every owner folder would land beside
+  // Documents and Downloads, and `adopt` would scan three levels of $HOME on
+  // every run. Refused rather than warned: by the time the output scrolls past,
+  // the folders exist.
+  if (samePath(target, os.homedir())) {
+    fail('The home directory cannot be the workspace root.');
+    console.error(
+      `\n  Owner folders would land beside Documents and Downloads, and every\n` +
+        `  scan would walk three levels of your home directory.\n\n` +
+        `  Try:  ${c.bold(`talea init ${path.join(os.homedir(), loadManifest(null).workspace || 'Workspace')}`)}`,
+    );
+    process.exit(1);
+  }
+
+  // A workspace inside a workspace: the upward walk stops at the nearest
+  // .talea.json, so both would half-work and which one you got would depend on
+  // where you were standing.
+  const enclosing = findWorkspace(path.dirname(target));
+  if (enclosing) {
+    warn(`There is already a talea workspace at ${c.bold(enclosing)}.`);
+    plain(
+      c.dim(
+        `  Nesting one inside another means the one you get depends on which\n` +
+          `  folder you run from. Remove ${path.join(enclosing, STATE_FILE)} if it is stale.`,
+      ),
+    );
+  }
   const stateFile = path.join(target, STATE_FILE);
   const fresh = !existsSync(stateFile);
 

package/src/commands/list.js

@@ -81,6 +81,7 @@ export function run(opts) {
           r.fork ? c.dim('fork') : '',
           r.archived ? c.yellow('quiet') : '',
           r.missing ? c.yellow('not on github') : '',
+          r.ignore ? c.yellow('ignored') : '',
         ]
           .filter(Boolean)
           .join(' '),

package/src/workspace.js

@@ -46,12 +46,28 @@ export function requireWorkspace() {
 export function machineRepos(manifest, state) {
   const chosen = state.selected;
   if (!Array.isArray(chosen)) {
-    return manifest.repos.filter((r) => r.default && !r.archived);
+    return manifest.repos.filter((r) => r.default && !r.archived && !r.ignore);
   }
   const wanted = new Set(chosen.map((n) => n.toLowerCase()));
-  return manifest.repos.filter((r) => wanted.has(r.name.toLowerCase()));
+  return manifest.repos.filter((r) => wanted.has(r.name.toLowerCase()) && !r.ignore);
 }
 
+/**
+ * Repos talea is allowed to touch at all.
+ *
+ * `ignore: true` means something else owns that checkout — another workspace
+ * manager, a vendored tree, an SDK cache. Without it two tools that both
+ * organise repositories will each drag the same checkout back to where it
+ * thinks it belongs, on every run, forever. Found with a repo living inside a
+ * second workspace manager's tree on the same disk.
+ *
+ * This is stronger than not selecting it: `adopt` deliberately works over the
+ * whole catalogue rather than this machine's selection, because a stray
+ * checkout is worth moving whether or not the machine signed up for it. An
+ * ignored repo is out of even that.
+ */
+export const adoptable = (manifest) => manifest.repos.filter((r) => !r.ignore);
+
 /** Has this machine ever been asked what it wants? */
 export const hasChosen = (state) => Array.isArray(state.selected);