{"record":{"id":"a5948dfc76f49d78","repo":"gastownhall/beads","slug":"failed-to-pin-target-directory-identity-w","errorCode":null,"errorMessage":"failed to pin target directory identity: %w","messagePattern":"failed to pin target directory identity: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/worktree_cmd.go","lineNumber":1006,"sourceCode":"\t\t\"--untracked-files=all\",\n\t\t\"--ignore-submodules=none\",\n\t\t\"--ignored=matching\",\n\t)\n\tif err != nil {\n\t\treturn pinnedWorktreeTarget{}, fmt.Errorf(\"failed to inspect target cleanliness: %w\", err)\n\t}\n\n\theadOID := strings.TrimSpace(string(headOutput))\n\tif headOID == \"\" || headOID != worktree.headOID {\n\t\treturn pinnedWorktreeTarget{}, fmt.Errorf(\n\t\t\t\"target HEAD disagrees with git worktree registry (registry %q, target %q)\",\n\t\t\tworktree.headOID,\n\t\t\theadOID,\n\t\t)\n\t}\n\tpathInfo, err := os.Lstat(worktree.path)\n\tif err != nil {\n\t\treturn pinnedWorktreeTarget{}, fmt.Errorf(\"failed to pin target directory identity: %w\", err)\n\t}\n\tif pathInfo.Mode()&os.ModeSymlink != 0 || !pathInfo.IsDir() {\n\t\treturn pinnedWorktreeTarget{}, fmt.Errorf(\"target path is not a real directory: %s\", worktree.path)\n\t}\n\tgitDirInfo, err := os.Lstat(gitDir)\n\tif err != nil {\n\t\treturn pinnedWorktreeTarget{}, fmt.Errorf(\"failed to pin target git directory identity: %w\", err)\n\t}\n\tif gitDirInfo.Mode()&os.ModeSymlink != 0 || !gitDirInfo.IsDir() {\n\t\treturn pinnedWorktreeTarget{}, fmt.Errorf(\"target git directory is not a real directory: %s\", gitDir)\n\t}\n\tgitMarkerPath := filepath.Join(worktree.path, \".git\")\n\tgitMarkerInfo, err := os.Lstat(gitMarkerPath)\n\tif err != nil {\n\t\treturn pinnedWorktreeTarget{}, fmt.Errorf(\"failed to pin target git marker identity: %w\", err)\n\t}\n\tif gitMarkerInfo.Mode()&os.ModeSymlink != 0 || !gitMarkerInfo.Mode().IsRegular() {\n\t\treturn pinnedWorktreeTarget{}, fmt.Errorf(\"target git marker is not a regular file: %s\", gitMarkerPath)","sourceCodeStart":988,"sourceCodeEnd":1024,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/worktree_cmd.go#L988-L1024","documentation":"After HEAD verification, inspectWorktreeTarget calls os.Lstat on the worktree path to pin its on-disk identity. If Lstat fails — the path does not exist or is unreadable — this wrapped error is returned. Removal cannot proceed because the target directory cannot be identified.","triggerScenarios":"The registered worktree directory was deleted or renamed after registry listing but before inspection; a race where another process removes the directory between listing and Lstat; permission denied on a parent directory; revalidation on a vanished directory.","commonSituations":"Manual `rm -rf` of a worktree without `git worktree remove`; a build/CI cleaner deleting stale directories; unmounted network volume making the path temporarily disappear; moved path in the registry.","solutions":["Confirm the directory exists with `ls <path>`; if gone, run `git worktree prune` and clean the bd registry entry instead of removing.","If the path moved, update the registration to the new path and retry.","Restore access to the parent directory or remount the volume, then retry.","Stop any racing process that deletes the directory mid-operation."],"exampleFix":"// before\nbd worktree remove feature-x\n// error: failed to pin target directory identity: lstat ...: no such file or directory\n// after\ngit worktree prune\nbd worktree list   # entry gone; nothing to remove","handlingStrategy":"validation","validationCode":"import { existsSync, statSync } from \"node:fs\";\nif (!existsSync(worktreePath) || !statSync(worktreePath).isDirectory()) {\n  throw new Error(\"worktree directory missing — prune registry instead of removing\");\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use `git worktree remove`/`bd worktree remove` instead of rm -rf.","Exclude worktree paths from aggressive cleanup scripts.","Remount network volumes before operating on worktrees.","Reconcile the registry after any manual directory moves."],"tags":["worktree","filesystem","lstat","missing-directory"],"backgroundTag":"path-not-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}