git-worktree-organize 1.1.0 → 1.1.1

package/README.md

@@ -1,24 +1,24 @@
 # git-worktree-organize
 
-> ⚠️ **Use at your own risk.** This tool works for me and passes all tested scenarios, but it modifies your git repository structure. **Make a full backup first** before running on any repository you care about.
+Convert any git repository into a bare-hub worktree layout where every branch lives in its own directory. No more stashing, no more switching.
 
-Convert any git repository into the canonical bare-hub worktree layout, so every branch lives in its own directory and you never need to stash or switch again.
+> **Use at your own risk.** This tool modifies your git repository structure. Always ensure you have a copy of important repositories before running it.
 
-## What it does
+> **Opinionated layout.** This tool enforces a specific structure where every branch is a sibling directory under a single hub root. If you prefer a different worktree arrangement, this tool may not be for you. See [Why this layout?](#why-this-layout) for the rationale.
 
-Takes an existing git repo (any type) and migrates it into this structure:
+## The target layout
 
 ```
-<dest>/
+myrepo/
 ├── .bare/       ← bare git repo (the actual git database)
 ├── .git         ← plain file: "gitdir: ./.bare"
 ├── main/        ← worktree for the main branch
 └── feature-x/   ← worktree for each other branch
 ```
 
-Each branch directory is a fully functional working tree. Open them in separate terminals or IDE windows simultaneously — no stashing, no switching.
+Each branch directory is a fully functional working tree. Open them in separate terminals or IDE windows simultaneously.
 
-The `.git` file at the hub root makes tools that walk up looking for `.git` (IDEs, linters, etc.) find the repo correctly.
+The `.git` file at the hub root means `git worktree list` (and any git command) works from **anywhere** -- the hub root, any worktree directory, or even nested subdirectories. IDEs, linters, and other tools that walk up looking for `.git` also find the repo correctly.
 
 ## Installation
 
@@ -39,145 +39,267 @@ git-worktree-organize <source> [destination]
 git-worktree-organize <source> [destination]
 ```
 
-| Argument      | Description                                                      |
-|---------------|------------------------------------------------------------------|
-| `source`      | Path to the existing git repository to migrate                   |
-| `destination` | Target hub directory (omit for in-place migration prompt)        |
-
-**Without a destination**, the tool prompts for in-place migration:
-- Renames `<source>` to `<source>.old`
-- Creates the hub at the original `<source>` path
-
-**With a destination**, the tool migrates to the specified path.
+| Argument      | Description                                                |
+|---------------|------------------------------------------------------------|
+| `source`      | Path to the existing git repository to migrate             |
+| `destination` | Target hub directory (omit for in-place migration)         |
 
 The tool shows a preview of what will be created and asks for confirmation before making any changes.
 
-## Examples
+### In-place migration
 
-### In-place migration (recommended)
+When no destination is provided, the tool prompts to migrate in place:
+
+1. Renames `<source>` to `<source>.old`
+2. Creates the hub at the original `<source>` path
 
 ```sh
 git-worktree-organize /projects/myrepo
 ```
 
-Prompts to reorganize in place, resulting in:
+Result:
 
 ```
-/projects/myrepo/          ← hub (was renamed from myrepo.old)
+/projects/myrepo/              ← new hub
 ├── .bare/
 ├── .git
 ├── main/
 └── feature-x/
 
-/projects/myrepo.old/      ← backup of original
+/projects/myrepo.old/          ← original repo (renamed)
 ```
 
-### Migrate to new location
+The `.old` directory is kept so you can verify the migration before deleting it manually.
+
+### Migration to a new location
+
+When a destination is provided, the source repo is moved into the new hub as the main branch worktree:
 
 ```sh
-git-worktree-organize /projects/myrepo /projects/myrepo-organized
+git-worktree-organize /projects/myrepo /projects/myrepo-hub
 ```
 
 Result:
 
 ```
-/projects/myrepo-organized/
+/projects/myrepo-hub/
 ├── .bare/
 ├── .git
-├── main/          ← original /projects/myrepo moved here
+├── main/              ← original /projects/myrepo moved here
 ├── feature-x/
 └── hotfix/
 ```
 
-The original `/projects/myrepo` becomes the `main/` worktree. No data is lost.
+The original source directory becomes the `main/` worktree. No data is lost.
+
+## Supported repository types
+
+The tool detects and migrates five different git repository layouts:
 
-## Features
+| Type | Description |
+|------|-------------|
+| **Standard** | Ordinary repo with a `.git` directory |
+| **Bare root** | Bare repo with git internals at the root (`HEAD`, `refs/`, `objects/`) |
+| **Bare dotgit** | Repo where `.git` is a bare directory (`core.bare = true`) |
+| **Bare external** | Repo where `.git` is a file pointing to a gitdir elsewhere |
+| **Bare hub** | Already in the bare-hub layout (re-organizes worktrees into canonical structure) |
 
-### Repository Migration
+See [Layout conversions](#layout-conversions) for detailed before/after diagrams of each type.
 
-Convert any git repository type to the bare-hub layout:
+## Recovery
 
-- **Standard repos** — ordinary repos with a `.git` directory
-- **Bare-root** — bare repo with git internals at the root (`HEAD`, `refs/`, `objects/`)
-- **Bare-dotgit** — repo where `.git` is a bare git directory (`core.bare = true`)
-- **Bare-external** — repo where `.git` is a file pointing to a gitdir elsewhere
-- **Bare-hub** — already in the bare-hub layout (re-organizes worktrees into the canonical structure)
+Running the tool on an existing hub detects problems and offers to fix them:
 
-### Resume & Recovery
+- **Partial migrations** -- Resumes moving worktrees that weren't fully processed (e.g. after an interruption).
+- **Stale `.git` pointers** -- Repairs worktrees with broken connections to the bare repo.
+- **Missing worktrees** -- Searches for worktrees that were moved outside the hub (up to 3 directory levels deep).
+- **Parent directory renames** -- Detects and repairs when a hub's parent directory was renamed.
 
-If a migration was interrupted or worktrees have moved, running the tool on the hub directory will:
+```sh
+# Resume a partial migration or repair an existing hub
+git-worktree-organize /path/to/hub
 
-1. **Resume partial migrations** — Continue moving worktrees that weren't fully processed
-2. **Repair stale `.git` pointers** — Fix worktrees with broken connections to the bare repo
-3. **Search for missing worktrees** — Find worktrees that were moved outside the hub (searches up to 3 directory levels deep)
-4. **Fix parent directory renames** — Automatically detect and repair when a hub's parent directory was renamed
+# Repair after renaming a parent directory (can point to any worktree inside the hub)
+git-worktree-organize /new/path/to/hub/some-worktree
+```
 
-### Safety Features
+## Safety
 
-- **Interactive confirmation** — Preview all changes before execution
-- **Branch name sanitization** — Names with slashes (e.g. `feature/auth`) become hyphenated directories (`feature-auth`)
-- **Collision detection** — Warns if sanitized names would conflict
-- **Zero runtime dependencies** — Only requires Node.js and git
+- **Interactive confirmation** -- Preview all changes before execution
+- **Branch name sanitization** -- Slashes become hyphens (e.g. `feature/auth` becomes `feature-auth`)
+- **Collision detection** -- Warns if sanitized names would conflict
+- **AI agent documentation** -- Creates an `AGENTS.md` at the hub root for AI coding agents (never overwrites existing files)
+- **Zero runtime dependencies** -- Only requires Node.js and git
 
-## Recovery Scenarios
+## Why this layout?
 
-### Partial Migration
+Every branch as a sibling directory means you can work on multiple branches simultaneously. Run branch-specific builds side by side. No stashing, no context switching.
 
-If migration was interrupted:
+The `.git` file at the hub root is the key detail. Because it points to `.bare/`, git resolves the repository from any location in the tree:
 
 ```sh
-git-worktree-organize /path/to/hub
+# All of these work -- no -C flag or cd needed:
+~/projects/myrepo $ git worktree list
+~/projects/myrepo/main $ git worktree list
+~/projects/myrepo/feature-x $ git worktree list
+~/projects/myrepo/main/src/deep/nested $ git worktree list
 ```
 
-The tool detects the partial state, shows which worktrees still need to be moved, and offers to resume.
+IDEs, linters, pre-commit hooks, and AI coding agents all discover the repo automatically regardless of which worktree directory they're opened in.
+
+## Requirements
 
-### Moved Worktrees
+- Node.js 18+
+- Git 2.5+ (for worktree support)
 
-If worktrees were manually moved outside the hub:
+## Development
 
 ```sh
-git-worktree-organize /path/to/hub
+git clone https://github.com/drmikecrowe/git-worktree-organize.git
+cd git-worktree-organize
+npm install
+
+npm test              # Run tests
+npm run build         # Build
+node dist/cli.js /path/to/test/repo   # Test locally
 ```
 
-The tool searches for missing worktrees by branch name and offers to repair their `.git` pointers.
+## Layout conversions
 
-### Parent Directory Rename
+Detailed before/after diagrams for each supported repository type.
 
-If you renamed a parent directory, worktree `.git` files will have stale paths. Run the tool on any worktree path inside the hub:
+### Standard repository
 
-```sh
-git-worktree-organize /new/path/to/hub/some-worktree
+The most common case -- a normal repo with a `.git` directory and optionally some linked worktrees.
+
+**Before:**
+```
+myrepo/
+├── .git/              ← standard git directory
+├── src/
+└── package.json
+
+myrepo-feature/        ← linked worktree (created by git worktree add)
+├── .git               ← file pointing back to myrepo/.git/worktrees/feature
+├── src/
+└── package.json
 ```
 
-The tool detects the hub, navigates to it, and repairs all worktree connections.
+**After:**
+```
+myrepo/
+├── .bare/             ← bare git repo (contents of old .git/)
+├── .git               ← file: "gitdir: ./.bare"
+├── AGENTS.md
+├── main/              ← main branch worktree (was myrepo/)
+│   ├── src/
+│   └── package.json
+└── feature/           ← feature worktree (was myrepo-feature/)
+    ├── .git           ← file pointing to .bare/worktrees/feature
+    ├── src/
+    └── package.json
+```
 
-## Why this layout
+### Bare root
 
-Having every branch as a sibling directory means you can work on multiple branches simultaneously without stashing or switching. It is also easier to run branch-specific build artifacts side by side, and the `.git` file at the hub root ensures IDE and tooling compatibility without any special configuration.
+A bare repository where git internals sit directly at the root. Often created by `git clone --bare` or `git init --bare`.
 
-## Requirements
+**Before:**
+```
+myrepo.git/
+├── HEAD
+├── config
+├── objects/
+└── refs/
+```
 
-- Node.js 18+
-- Git 2.5+ (for worktree support)
+**After:**
+```
+myrepo-hub/
+├── .bare/             ← git internals moved here
+│   ├── HEAD
+│   ├── config
+│   ├── objects/
+│   └── refs/
+├── .git               ← file: "gitdir: ./.bare"
+└── AGENTS.md
+```
 
-## Development
+No worktrees are created since a bare repo has no checked-out branches. Use `git worktree add <branch>` from the hub to start working.
 
-```sh
-# Clone and install
-git clone https://github.com/drmikecrowe/git-worktree-organize.git
-cd git-worktree-organize
-npm install
+### Bare dotgit
+
+A repository where `.git` is a directory but `core.bare = true`.
+
+**Before:**
+```
+myrepo/
+└── .git/              ← directory, but core.bare = true
+    ├── HEAD
+    ├── config         ← contains core.bare = true
+    ├── objects/
+    └── refs/
+```
+
+**After:**
+```
+myrepo-hub/
+├── .bare/             ← contents of old .git/
+├── .git               ← file: "gitdir: ./.bare"
+└── AGENTS.md
+```
 
-# Run tests
-npm test
+### Bare external
 
-# Build
-npm run build
+A repository where `.git` is a file pointing to a gitdir stored elsewhere on the filesystem.
 
-# Test locally
-node dist/cli.js /path/to/test/repo
+**Before:**
+```
+myrepo/
+├── .git               ← file: "gitdir: /somewhere/else/myrepo.git"
+├── src/
+└── package.json
+
+/somewhere/else/myrepo.git/
+├── HEAD
+├── objects/
+└── refs/
+```
+
+**After:**
+```
+myrepo-hub/
+├── .bare/             ← copy of /somewhere/else/myrepo.git/
+├── .git               ← file: "gitdir: ./.bare"
+└── AGENTS.md
+```
+
+### Bare hub (re-organize)
+
+Already in the bare-hub layout but with worktrees scattered in non-standard locations.
+
+**Before:**
+```
+myrepo/
+├── .bare/
+├── .git               ← file: "gitdir: ./.bare"
+└── main/
+
+/other/path/feature/   ← worktree outside the hub
+└── .git
+```
+
+**After:**
+```
+myrepo/
+├── .bare/
+├── .git               ← file: "gitdir: ./.bare"
+├── AGENTS.md
+├── main/
+└── feature/           ← moved into the hub
+    └── .git           ← repaired to point to .bare/worktrees/feature
 ```
 
 ## License
 
-MIT — see [github.com/drmikecrowe/git-worktree-organize](https://github.com/drmikecrowe/git-worktree-organize).
+MIT -- see [github.com/drmikecrowe/git-worktree-organize](https://github.com/drmikecrowe/git-worktree-organize).

package/dist/cli.js

@@ -2,7 +2,7 @@
 
 // src/cli.ts
 import { resolve as resolve3, join as join5, dirname as dirname3, basename as basename3 } from "node:path";
-import { existsSync as existsSync5, statSync as statSync5, readFileSync as readFileSync5 } from "node:fs";
+import { existsSync as existsSync5, statSync as statSync5, readFileSync as readFileSync5, readdirSync as readdirSync3 } from "node:fs";
 
 // src/run.ts
 import { spawnSync } from "node:child_process";
@@ -144,6 +144,103 @@ function samefs(a, b) {
 }
 
 // src/migrate.ts
+var AGENTS_MD_TEMPLATE = `# Git Worktree Layout
+
+This repository uses **git worktrees** with a bare repository pattern for parallel development across multiple branches.
+
+## Directory Structure
+
+\`\`\`
+<project>/                        # Root project directory
+\u251C\u2500\u2500 .bare/                        # Bare git repository (shared git data)
+\u2502   \u251C\u2500\u2500 worktrees/               # Worktree metadata
+\u2502   \u2502   \u251C\u2500\u2500 main/                # Main branch metadata
+\u2502   \u2502   \u2514\u2500\u2500 <branch-name>/       # Per-branch worktree metadata
+\u2502   \u251C\u2500\u2500 objects/                 # Git objects (shared)
+\u2502   \u251C\u2500\u2500 refs/                    # Git refs (shared)
+\u2502   \u2514\u2500\u2500 config                   # Repository config
+\u251C\u2500\u2500 .git                         # Points to .bare (gitdir: ./.bare)
+\u251C\u2500\u2500 main/                        # Main branch worktree (primary)
+\u251C\u2500\u2500 <branch-name>/               # Feature/fix branch worktrees
+\u2514\u2500\u2500 *.code-workspace             # VS Code multi-root workspace
+\`\`\`
+
+## How It Works
+
+- **Bare Repository**: \`.bare/\` contains all git data (objects, refs, config)
+- **Worktrees**: Each branch checkout is a separate directory at the root level
+- **Shared History**: All worktrees share the same git history from \`.bare/\`
+
+## Working with Worktrees
+
+### Create a new worktree
+
+\`\`\`bash
+# From any worktree or the root
+git worktree add <branch-name>
+
+# Create new branch and worktree
+git worktree add -b <new-branch> <directory-name>
+\`\`\`
+
+### List worktrees
+
+\`\`\`bash
+git worktree list
+\`\`\`
+
+### Remove a worktree
+
+\`\`\`bash
+# After merging/deleting the branch
+git worktree remove <branch-name>
+
+# Force removal (if untracked files exist)
+git worktree remove --force <branch-name>
+\`\`\`
+
+### Prune stale worktree references
+
+\`\`\`bash
+git worktree prune
+\`\`\`
+
+## Conventions
+
+1. **Naming**: Worktree directories match the branch name (e.g., \`feature-auth\`, \`fix-login-bug\`)
+2. **Main worktree**: \`main/\` is the primary worktree for the main branch
+3. **Workspace file**: Open \`*.code-workspace\` in VS Code to work with multiple worktrees
+
+## Tips
+
+- Each worktree has its own \`.git\` file pointing back to \`.bare/\`
+- You can run different branches simultaneously without stashing
+- IDEs can open multiple worktrees as separate folders in one workspace
+- Run \`git worktree prune\` periodically to clean up deleted worktree references
+`;
+function writeAgentsMd(dest) {
+  const agentsPath = join2(dest, "AGENTS.md");
+  if (!existsSync3(agentsPath)) {
+    writeFileSync(agentsPath, AGENTS_MD_TEMPLATE);
+  }
+}
+function worktreeConfigEnabled(bareDir) {
+  const configFile = join2(bareDir, "config");
+  if (!existsSync3(configFile)) return false;
+  const content = readFileSync2(configFile, "utf8");
+  const extensionsMatch = content.match(/\[extensions\]([\s\S]*?)(?=\[|$)/i);
+  if (!extensionsMatch) return false;
+  return /worktreeconfig\s*=\s*true/i.test(extensionsMatch[1]);
+}
+var WORKTREE_CONFIG_CONTENT = "[core]\n	bare = false\n";
+function ensureWorktreeConfig(adminDir, bareDir, log) {
+  if (!worktreeConfigEnabled(bareDir)) return;
+  const configWtFile = join2(adminDir, "config.worktree");
+  if (!existsSync3(configWtFile) || readFileSync2(configWtFile, "utf8") !== WORKTREE_CONFIG_CONTENT) {
+    log?.(`Writing config.worktree for [${basename(adminDir)}]`);
+    writeFileSync(configWtFile, WORKTREE_CONFIG_CONTENT);
+  }
+}
 function sanitizeBranch(branch) {
   return branch.replace(/\//g, "-");
 }
@@ -180,6 +277,13 @@ async function repairHub(dest, log = console.log) {
     const worktreePath = dirname2(registeredGitFile);
     if (!worktreePath.startsWith(dest + "/")) continue;
     if (!existsSync3(registeredGitFile) || !statSync3(registeredGitFile).isFile()) continue;
+    const commondirFile = join2(adminDir, "commondir");
+    const expectedCommondir = "../../\n";
+    if (!existsSync3(commondirFile) || readFileSync2(commondirFile, "utf8") !== expectedCommondir) {
+      log(`Repairing commondir for [${basename(worktreePath)}]`);
+      writeFileSync(commondirFile, expectedCommondir);
+    }
+    ensureWorktreeConfig(adminDir, join2(dest, ".bare"), log);
     const content = readFileSync2(registeredGitFile, "utf8");
     const match = content.match(/^gitdir:\s*(.+)/m);
     if (!match) continue;
@@ -266,6 +370,7 @@ async function migrateInPlace(source, log = console.log, warn) {
   mkdirSync(mainAdminDir, { recursive: true });
   writeFileSync(join2(mainAdminDir, "gitdir"), mainDest + "/.git\n");
   writeFileSync(join2(mainAdminDir, "commondir"), "../../\n");
+  ensureWorktreeConfig(mainAdminDir, destBare);
   const headToWrite = mainHeadContent.endsWith("\n") ? mainHeadContent : mainHeadContent + "\n";
   writeFileSync(join2(mainAdminDir, "HEAD"), headToWrite);
   const bareIndex = join2(destBare, "index");
@@ -279,6 +384,7 @@ async function migrateInPlace(source, log = console.log, warn) {
     await processLinkedWorktree(worktrees[i], resolvedSource, destBare, log, warn);
   }
   log(`Original repo backed up at: ${oldPath}`);
+  writeAgentsMd(resolvedSource);
   return resolvedSource;
 }
 function bold(s) {
@@ -322,6 +428,7 @@ async function migrate(config, options, log, warn) {
     mkdirSync(mainAdminDir, { recursive: true });
     writeFileSync(join2(mainAdminDir, "gitdir"), mainDest + "/.git\n");
     writeFileSync(join2(mainAdminDir, "commondir"), "../../\n");
+    ensureWorktreeConfig(mainAdminDir, destBare);
     const headToWrite = mainHeadContent.endsWith("\n") ? mainHeadContent : mainHeadContent + "\n";
     writeFileSync(join2(mainAdminDir, "HEAD"), headToWrite);
     const bareIndex = join2(destBare, "index");
@@ -338,6 +445,7 @@ async function migrate(config, options, log, warn) {
       await processLinkedWorktree(wt, dest, destBare, log, warn);
     }
   }
+  writeAgentsMd(dest);
   return dest;
 }
 async function processLinkedWorktree(wt, dest, destBare, log, warn) {
@@ -359,6 +467,8 @@ async function processLinkedWorktree(wt, dest, destBare, log, warn) {
 `);
   if (existsSync3(newAdmin)) {
     writeFileSync(join2(newAdmin, "gitdir"), wtDest + "/.git\n");
+    writeFileSync(join2(newAdmin, "commondir"), "../../\n");
+    ensureWorktreeConfig(newAdmin, destBare);
   } else {
     warn?.(`Admin dir ${newAdmin} does not exist for worktree ${wtDest}`);
   }
@@ -481,12 +591,78 @@ function isGitPointerValid(worktreePath, hubPath) {
   if (!match) {
     return false;
   }
-  const gitdir = match[1].trim();
+  const adminDir = match[1].trim();
   const bareDir = join5(hubPath, ".bare");
-  return gitdir.includes(bareDir) && gitdir.includes("/worktrees/");
+  if (!adminDir.includes(bareDir) || !adminDir.includes("/worktrees/")) {
+    return false;
+  }
+  if (!existsSync5(adminDir)) {
+    return false;
+  }
+  const adminGitdirFile = join5(adminDir, "gitdir");
+  if (!existsSync5(adminGitdirFile)) {
+    return false;
+  }
+  const adminGitdir = readFileSync5(adminGitdirFile, "utf8").trim();
+  if (adminGitdir !== gitFile) {
+    return false;
+  }
+  const commondirFile = join5(adminDir, "commondir");
+  if (!existsSync5(commondirFile) || readFileSync5(commondirFile, "utf8").trim() !== "../..") {
+    return false;
+  }
+  const sharedConfig = join5(hubPath, ".bare", "config");
+  if (existsSync5(sharedConfig)) {
+    const cfg = readFileSync5(sharedConfig, "utf8");
+    const extMatch = cfg.match(/\[extensions\]([\s\S]*?)(?=\[|$)/i);
+    if (extMatch && /worktreeconfig\s*=\s*true/i.test(extMatch[1])) {
+      const configWt = join5(adminDir, "config.worktree");
+      if (!existsSync5(configWt) || !readFileSync5(configWt, "utf8").includes("bare = false")) {
+        return false;
+      }
+    }
+  }
+  try {
+    run("git", ["-C", worktreePath, "rev-parse", "HEAD"]);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function listWorktreesFromAdminDirs(hubPath) {
+  const adminBase = join5(hubPath, ".bare", "worktrees");
+  if (!existsSync5(adminBase)) return [];
+  const worktrees = [];
+  for (const adminName of readdirSync3(adminBase)) {
+    const adminDir = join5(adminBase, adminName);
+    if (!statSync5(adminDir).isDirectory()) continue;
+    const gitdirFile = join5(adminDir, "gitdir");
+    if (!existsSync5(gitdirFile)) continue;
+    const wtGitFile = readFileSync5(gitdirFile, "utf8").trim();
+    const wtPath = dirname3(wtGitFile);
+    const headFile = join5(adminDir, "HEAD");
+    let branch = null;
+    let head = "";
+    if (existsSync5(headFile)) {
+      const headContent = readFileSync5(headFile, "utf8").trim();
+      if (headContent.startsWith("ref: refs/heads/")) {
+        branch = headContent.slice("ref: refs/heads/".length);
+      } else {
+        head = headContent;
+      }
+    }
+    worktrees.push({ path: wtPath, head, branch, isBare: false });
+  }
+  return worktrees;
 }
 async function runValidationMode(hubPath) {
-  const worktrees = await listWorktrees(hubPath);
+  let worktrees;
+  try {
+    worktrees = await listWorktrees(hubPath);
+  } catch {
+    console.log(`${yellow("warn:")} git worktree list failed; scanning admin dirs to enumerate worktrees`);
+    worktrees = listWorktreesFromAdminDirs(hubPath);
+  }
   const validated = [];
   for (const wt of worktrees) {
     if (wt.isBare) continue;
@@ -539,12 +715,18 @@ async function runValidationMode(hubPath) {
   if (counts.missing > 0) summaryParts.push(`${counts.missing} missing`);
   if (counts.stale > 0) summaryParts.push(`${counts.stale} stale`);
   console.log(`Summary: ${summaryParts.join(", ")}`);
-  const needsRepair = validated.filter((v) => v.status === "missing" || v.status === "stale");
+  const staleWorktrees = validated.filter((v) => v.status === "stale");
+  if (staleWorktrees.length > 0) {
+    console.log();
+    console.log(`${green("==>")} Auto-repairing ${staleWorktrees.length} stale worktree(s)...`);
+    await repairHub(hubPath, (msg) => console.log(`  ${msg}`));
+  }
+  const needsRepair = validated.filter((v) => v.status === "missing");
   if (needsRepair.length === 0) {
     return;
   }
   console.log();
-  console.log(`${yellow("warn:")} ${needsRepair.length} worktree(s) need repair.`);
+  console.log(`${yellow("warn:")} ${needsRepair.length} missing worktree(s) need repair.`);
   const searchDirs = [dirname3(hubPath)];
   console.log(`${green("==>")} Searching for missing worktrees...`);
   const results = await findMissingWorktrees(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "git-worktree-organize",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Convert any git repo into the canonical bare-hub worktree layout",
   "type": "module",
   "bin": {