What causes "failed to inspect target cleanliness: %w" in gastownhall/beads?

Run `git -C status` manually to see the underlying error and fix it (e.g. remove a stale index.lock — only when no git process is running).

gastownhall/beads · error

failed to inspect target cleanliness: %w

Error message

failed to inspect target cleanliness: %w

What it means

inspectWorktreeTarget runs `git status --porcelain=v1 -z --untracked-files=all --ignore-submodules=none --ignored=matching` to snapshot the worktree's cleanliness before removal. If git status itself fails, this wrapped error is returned. bd requires a reliable status fingerprint before removing a worktree.

Source

Thrown at cmd/bd/worktree_cmd.go:993

		"--quiet",
		"--end-of-options",
		"HEAD^{commit}",
	)
	if err != nil {
		return pinnedWorktreeTarget{}, fmt.Errorf("target HEAD does not resolve to a commit: %w", err)
	}
	statusOutput, err := git.output(
		ctx,
		worktree.path,
		"status",
		"--porcelain=v1",
		"-z",
		"--untracked-files=all",
		"--ignore-submodules=none",
		"--ignored=matching",
	)
	if err != nil {
		return pinnedWorktreeTarget{}, fmt.Errorf("failed to inspect target cleanliness: %w", err)
	}

	headOID := strings.TrimSpace(string(headOutput))
	if headOID == "" || headOID != worktree.headOID {
		return pinnedWorktreeTarget{}, fmt.Errorf(
			"target HEAD disagrees with git worktree registry (registry %q, target %q)",
			worktree.headOID,
			headOID,
		)
	}
	pathInfo, err := os.Lstat(worktree.path)
	if err != nil {
		return pinnedWorktreeTarget{}, fmt.Errorf("failed to pin target directory identity: %w", err)
	}
	if pathInfo.Mode()&os.ModeSymlink != 0 || !pathInfo.IsDir() {
		return pinnedWorktreeTarget{}, fmt.Errorf("target path is not a real directory: %s", worktree.path)
	}
	gitDirInfo, err := os.Lstat(gitDir)

View on GitHub (pinned to 71377f2769)

Solutions

Run `git -C <path> status` manually to see the underlying error and fix it (e.g. remove a stale index.lock — only when no git process is running).
Fix permissions on the worktree directory so the current user can read it.
Deinit or repair the offending submodule if it blocks status.
Retry after resolving; if the worktree is disposable, prune via `git worktree prune` and clear the registry.

Example fix

// before
bd worktree remove feature-x
// error: failed to inspect target cleanliness: ... index.lock exists
// after
git -C /repo/.worktrees/featurex status   # confirm no live git process, then:
rm -f /repo/.git/worktrees/feature-x/index.lock
bd worktree remove feature-x

Defensive patterns

Strategy: try-catch

Validate before calling

const st = Bun.spawnSync(["git", "-C", worktreePath, "status", "--porcelain"]);
if (st.exitCode !== 0) throw new Error("git status fails: " + st.stderr.toString());

Try / catch

try {
  await bd("worktree", "remove", path);
} catch (e) {
  if (String(e.message).includes("failed to inspect target cleanliness")) {
    // only if no git process is running:
    execSync(`rm -f /repo/.git/worktrees/${name}/index.lock`);
    // then retry
  } else throw e;
}

Prevention

Don't run concurrent git/bd operations on the same worktree.
Clean up crashed git processes and stale index.lock files.
Keep submodules healthy (`git submodule status`).
Ensure the worktree filesystem is mounted and readable.

When it happens

Trigger: `git status` failing inside the target worktree due to a broken or locked index (index.lock present), unreadable working tree, submodule errors, or a canceled/timed-out git subprocess during removal or revalidation.

Common situations: A concurrent git process crashed leaving index.lock; permissions changed on the worktree; a broken submodule blocks status; the filesystem is unavailable (unmounted network volume).

Related errors

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/001d9db33e5be938. Report an issue: GitHub.