pitfalls

Pitfalls

Past traps we've stepped on. Symptoms-first knowledge base — the goal is that when a problem recurs (on a new machine, after an upgrade, with a new tool combo), grepping the symptom here lands you on the root cause and workaround in seconds, instead of re-debugging from scratch.

This folder is chezmoi-ignored (see .chezmoiignore.tmpl → pitfalls/**); it is repo metadata for maintainers, not user-facing config to deploy.

Pitfalls vs the rest

This repo has four sibling surfaces with overlapping shapes; pick the right one:

Surface	Time direction	Question it answers	Access pattern
docs/tools/<tool>.md	Present	"How does this tool work / how do I configure it?"	Read top to bottom
docs/this_repo/<topic>.md	Present	"Why did we architect it this way?"	Read top to bottom
pitfalls/<slug>.md	Past	"I see error X — has this happened before?"	Grep symptoms
backlog/<slug>.md	Future	"We thought about doing Y — what was the analysis?"	Index in TODO.md
AGENTS.md Hard invariants	Present	"What rules MUST agents follow?"	Read top to bottom

A pitfall graduates to a Hard invariant in AGENTS.md when the trap is serious enough that you can't rely on memory or grep — typically when (a) it recurs across machines, (b) it silently corrupts state, or (c) the workaround is non-obvious and easy to undo by accident. When graduating, leave a pitfalls/<slug>.md as historical record and link to it from the invariant.

When to add a pitfall doc

Add a pitfalls/<slug>.md when you've spent more than ~15 minutes on something where the answer wasn't googleable, AND any of:

• The symptom is non-obvious from the root cause (SSH_CONNECTION cleared silently → hostname module disappears, no error)
• The fix is "do nothing different but in a specific order" (sentinel writes must come after wait $pid for fleet-apply, etc.)
• The same trap could be hit by a new agent / new machine / new contributor
• An upstream bug exists with no ETA — workaround needs to outlive memory
• A specific tool version is required (or forbidden) and the failure mode at the wrong version is silent / confusing (e.g. tmux 3.2a popup off-screen)

When NOT to add a pitfall doc

• Trivially googleable error (the next person will solve in 30 seconds anyway)
• Already covered in docs/tools/<tool>.md as part of the tool's normal configuration — cross-link from this README's "Cross-referenced pitfalls" table below instead of duplicating
• Already a AGENTS.md Hard invariant — those have higher priority enforcement (cross-link only)
• One-off transient (network glitch, machine-specific config rot) — fix and move on

File template

See assets/pitfall-doc.md.template in the project-knowledge-harness skill, or copy the structure of an existing entry below.

Key sections (different from backlog/ template — symptom-first, not context-first):

# <Title describing the SYMPTOM, not the root cause>

**Symptoms** (grep this section): <verbatim error messages, observable behaviour>
**First seen**: YYYY-MM
**Affects**: <tool/version/OS combo>
**Status**: workaround documented / fixed upstream in vX.Y / WONTFIX

## Symptom

Full error messages (verbatim, not paraphrased — preserves grep-ability).
Reproduction steps if applicable.

## Root cause

Why this happens. Reference source, docs, or upstream issue.

## Workaround

Immediate workaround (commands, config diff). Should be copy-pasteable.

## Prevention

How to avoid stepping on this again. If serious enough, link to the
corresponding `AGENTS.md` Hard invariant.

## Related

Links to `docs/`, sibling pitfalls, `TODO.md` entries (if a real fix is
queued), upstream issues/PRs.

Index

Pitfalls owned by this folder. Keep alphabetical.

Slug	Symptom keywords	Status
agent-warmup-scheduled-run-hangs-or-blank-under-daemon	launchd/pueue agent-warmup run wedges for hours (state = running, no log) or finishes with an EMPTY /usage panel / blank capture-pane; sample shows dyld mapFileReadOnly; stuck PID is uv or python3 .../agent-warmup; identical agent-warmup verify works by hand	fixed (4 stacked fixes: direct python · lazy plistlib · main-volume python · inject into the existing GUI-session tmux server)
ansible-js-cli-tools-old-system-node	Tag 'js_cli_tools' had failures / Tag 'coding_agents' had failures; npm WARN EBADENGINE + EACCES /usr/local/lib/node_modules; system node v12.22.9 on Ubuntu jammy	fix paths documented (no in-repo fix yet)
ansible-missing-sudo-tag	chezmoi apply in noRoot mode aborts at one ansible task with sudo: a password is required / Premature end of stream waiting for become success; works fine on rooted hosts	workaround documented (add tags: [sudo]); convention = every become: true in dot_ansible/ must pair with tags: [sudo]
apt-update-fails-base-role-empty-error	Failed to update apt cache after 5 retries: '' (empty reason) at base role; Failed to update cache after 5 retries due to , retrying; chezmoi init exit 1 on Debian/Ubuntu; GFW host with unreachable third-party repo / dead lazygit PPA leftover	fixed (best-effort cache update + CLI diagnostics; lazygit PPA removed + purged; deb822 migration with policy-probe rollback)
bitwarden-ssh-agent-confirm-blocks-remote-git-push	git push / ssh fails Connection closed by … port 443 + Could not read from remote repository when $SSH_AUTH_SOCK is Bitwarden's agent and you're on a remote/headless session; intermittent (first push OK, later fail); ssh-add -l still lists the key	by design — disable per-use confirm, approve at the physical screen, ssh -A forward, or use HTTPS+PAT
blesh-set-v-leaks-gexec-wrapper	{ _ble_edit_exec_gexec__save_lastarg "$@"; } 4>&1 5>&2 &>/dev/null printed after every prompt under bash + ble.sh; typed command echoed twice; goes away in fresh terminal; no + prefix (so not set -x)	workaround = set +v in-session; set -v is architecturally incompatible with ble.sh's eval-based gexec
bootstrap-curl-bash-hangs-after-reattaching-tty	curl … | bash of bootstrap.sh hangs forever right after [bootstrap …] stdin is a pipe — reattaching to /dev/tty for interactive prompts; no fetching + running … log; no uv/chezmoi child process; only happens on certain fresh users / hosts	fixed (exec </dev/tty removed mid-script; /dev/tty redirected only on the final exec uv run)
bootstrap-no-tty-sudo-prompt-skipped	[WARN] Could not establish a sudo session (no TTY and sudo needs a password) then Linuxbrew installer aborts with Insufficient permissions to install Homebrew to "/home/linuxbrew/.linuxbrew"; mkdir: cannot create directory '/run/user/<UID>': Permission denied; user verifiably has interactive sudo; CentOS 7 + high-UID AD/LDAP user	workaround documented (CHEZMOI_SUDO_PASSWORD_FILE / just apply-with-sudo / NOPASSWD: ALL sudoers drop-in)
brew-bundle-redownloads-manually-installed-cask	brew bundle re-downloads cask for .app already in /Applications/; chains into process has already locked .incomplete parallel-fetch errors; [WARN] Some packages in macOS packages from Brewfile.darwin still failed after 2 attempts	partial: stale-lock cleanup permanent; --adopt pre-flight opt-in via CHEZMOI_BREW_ADOPT_PREFLIGHT=1 (version-strict + password-storm trade-offs documented)
brew-cask-slow-github-release-assets	brew upgrade --cask <x> download creeps at ~25 KB/s from release-assets.githubusercontent.com; TUNA/ghproxy/Clash don't help	no workaround (network-path issue)
btop-themes-permission-denied-core-dumped	btop aborts on launch: IOT instruction (core dumped) + terminate called ... std::filesystem::filesystem_error / directory iterator cannot open directory: Permission denied [~/.config/btop/themes]; dir perms are fine (775 user-owned); command -v btop = /snap/bin/btop (publisher kz6fittycent)	not a repo bug; snap home interface can't read hidden dirs; workaround = sudo snap remove btop (or brew install btop) so apt/GitHub/brew btop wins on PATH
centos7-neovim-apt-register-defined	just ansible-tags neovim / chezmoi apply on sudo-having CentOS 7 box completes ok=8 changed=0 skipped=23 failed=0 but command -v nvim is empty; user-level fallback gated apt_neovim is not defined but register: on a when:-skipped task IS defined (as a skip dict); plus mainline nvim ≥0.10 binaries require glibc 2.28+ which EL7 lacks	fixed (gate adds or apt_neovim is skipped; oldEL branch downloads from upstream's neovim/neovim-releases older-glibc repo)
centos7-systemd-user-instance-missing	rust_cargo_tools : Enable and start pueued service fails with Failed to get D-Bus connection: No such file or directory, ansible ...ignoring; PLAY RECAP failed=0 but daemon never starts; sudo loginctl enable-linger $USER does NOT help; sudo systemctl start user@$(id -u).service returns Unit not found; find /usr/lib/systemd -name 'user@.service' is empty	WONTFIX upstream (RHEL 7 EOL); workaround = run pueued under tmux/nohup or as system service; ansible role's ignore_errors: true is correct
chezmoi-reinit-promptonce-keeps-stale-value	re-running chezmoi init / dotfiles_init.py doesn't change a setting; --promptBool "...=false" ignored, installX flag stays true; chezmoi data shows stale value after re-apply; no error	fixed (init re-init branch + reconfigure both pass --prompt)
chezmoi-update-blesh-local-changes-overwritten	chezmoi update / --refresh-externals aborts on .local/share/blesh: Your local changes to the following files would be overwritten by merge (lib/core-syntax.sh …); diff = added license header + stripped comments; nobody edited ble.sh source	fixed (source clone moved to ~/.local/src/blesh, decoupled from make install target)
chezmoiignore-negation-noop-under-recursive-glob	a new managed file under a **-ignored dir shows chezmoi: …: not managed; chezmoi managed | grep empty; !path re-include in .chezmoiignore silently does nothing; chezmoi apply exits 0 with no error	workaround documented (use single-* globs dir/* + dir/*/** so the parent stays un-excluded, then !dir/keep)
claude-code-permission-mode-resets-after-interactive-prompt	Claude Code drops from bypassPermissions / plan back to acceptEdits after answering any AskUserQuestion / CodeIsland popup / remote-control inject; Bash(...) then re-prompts for permission	workaround documented (permissions.defaultMode = "bypassPermissions" in overlay); WONTFIX upstream
claude-hud-usage-statusline-stale	agent-wakeup status says WAIT_QUOTA while Claude is active; tmux capture contains stale `Context ...	Usage ... Limit reached`; HUD usage line misread as quota-blocked pane
claude-plans-here-misses-global-plans-jsonl-schema	claude-plans-here prints only Wrote .../.claude/settings.json; project .claude/plans/ stays empty; matching plan still under ~/.claude/plans/*.md; JSONL uses toolUseResult.filePath / ExitPlanMode.planFilePath	fixed (find + jq parser; Bats fixture coverage)
codeisland-auto-approves-permissionrequest	Claude Code shows ⎿ Allowed by PermissionRequest hook / ⏺ Plan approved. instantly with no notch popup, no native confirm dialog; ~/.claude/settings.json contains a PermissionRequest hook pointing at ~/.codeisland/codeisland-hook.sh with timeout: 86400	workaround documented (toggle off auto-approve in the CodeIsland HUD app); repo-enforced subtractive removal designed but deliberately NOT wired up
editor-overlay-flattens-empty-settings	Cursor/VSCode/Antigravity loses workbench.colorTheme + workbench.iconTheme after chezmoi apply; settings.json collapses to ~286 bytes = only the 6 overlay keys; reverts to Dark Modern + no file icons; user blames the Brewfile cask reinstall (it's not); sibling editors untouched	by design (jq '. * $overlay' on an empty base yields overlay-only); recovery + optional guard documented
git-delta-empty-stdin-huge-allocation	delta / printf '' | delta crashes with memory allocation of 1970324836974592 bytes failed; delta --version still works; something is very wrong if the default theme is missing	fixed (clear incompatible bat cache + delta stdin health check)
git-lfs-global-hook-breaks-brew-tap	brew tap / brew bundle fails: This repository is configured for Git LFS but 'git-lfs' was not found on your path, git clone ... exited with 2, Tapping <tap> has failed!, then Cask '<name>' is unavailable: No Cask with this name exists; git-lfs IS installed; stock git-lfs hook in the global core.hooksPath exit 2s under Homebrew's stripped superenv PATH	fixed (chezmoi-managed git-lfs hooks made PATH-robust + non-fatal)
headless-claude-p-does-not-move-5h-window	scheduled claude -p 'Reply: hi' warmup runs clean (exit 0) but the Claude Pro/Max 5-hour window never starts; /usage shows no active window at warmup time; metered Agent SDK credit consumed instead of subscription; --bare forces ANTHROPIC_API_KEY	by design (2026-06-15 billing split) — agent-warmup drives an interactive tmux session instead
homebrew-6-refuses-untrusted-tap-formula	chezmoi apply dies at devtools : Install developer CLI tools (macOS) with Error: Refusing to load formula raine/workmux/workmux from untrusted tap; Run \brew trust raine/workmux`; brew tap-info showsUntrusted; both raine/workmuxanddlvhdr/formulae` affected; worked days earlier	fixed (devtools role auto-brew trusts third-party taps; Homebrew 6.0 formula-trust gate)
homebrew-aliyun-brew-git-hang-core-clone-bloat	any auto-updating brew cmd hangs 60s+ after HOMEBREW_BREW_GIT_REMOTE set: using https://mirrors.aliyun.com/homebrew/brew.git; unset HOMEBREW_BREW_GIT_REMOTE "fixes" it; git ls-remote fast but git fetch stalls; SEPARATELY du -sh "$(brew --repo homebrew/core)/.git" = ~1 GB after being ~8 KB	fixed (baseline Aliyun→BFSU across 3 layers + brew-mirror; HOMEBREW_CORE_GIT_REMOTE dropped — brew 4.x API mode)
macos-tcc-tmux-volumes-permission-denied	ls /Volumes/Data/... in Alacritty or an attached old tmux session prints Permission denied: . - code: 13 / Skipped 1 directories due to permission denied: ., while Cursor can read the same path and Unix perms are normal	workaround documented (Full Disk Access belongs to the app that started the tmux server; kill old server and restart tmux from the authorized app)
macfuse-too-old-unsupported-macos-version-rclone-mount	macFUSE dialog Unsupported macOS Version — The installed version of macFUSE is too old for the operating system on boot / rclone mount; rclone mount --help works fine (binary not the cause); brew info --cask macfuse reports 5.x but Caskroom has 4.x; brew upgrade doesn't fix (cask is auto_updates)	by design (kext version-locked to macOS major); manual brew reinstall --cask macfuse + reboot + GUI approval; not repo-managed
mkdocs-copy-to-llm-custom-css-no-trailing-newline	git status always shows docs/assets/copy-to-llm/copy-to-llm-custom.css modified after mkdocs build / mkdocs serve; diff is just -} / +} \ No newline at end of file; end-of-file-fixer adds \n back, next build strips it; ping-pong forever	workaround documented (gitignore + git rm --cached); upstream PR not yet sent
modify-script-jq-bootstrap-cycle	jq: command not found / chezmoi: .agents/.skill-lock.json: exit status 127 immediately after [SUCCESS] Bootstrap complete! on a fresh box; subsequent applies stuck in same loop because ansible never reached	fixed (command -v guards added to all 7 modify_* scripts that needed them)
tmux-continuum-restores-on-intentional-quit	closed tmux on purpose (kill-server / "Kill all sessions" / prefix + M-x on last session) and the just-killed sessions come back on next tmux start; @continuum-restore 'on' can't tell intent from crash; ~/.local/share/tmux/resurrect/last symlink still points at the pre-kill snapshot	workaround documented (clean-quit wrappers kill-server-clean.sh / kill-session-exit.sh rm the last symlink before server dies; crash recovery preserved via untouched history)
tmux-copy-mode-double-free-3.6a	[server exited unexpectedly] after long-running session when entering copy-mode; .ips shows ___BUG_IN_CLIENT_OF_LIBMALLOC_POINTER_BEING_FREED_WAS_NOT_ALLOCATED with stack cmd_copy_mode_exec → window_copy_clone_screen → screen_reinit → grid_clear_lines → grid_free_line; homebrew bottle slice_uuid: 1b2d8e7b-bb77-3465-8bab-73f5bbaffe49; terminal-agnostic	fixed upstream (035a2f3 closing #4777) but not in any tagged release; workaround = brew install --HEAD tmux until 3.7 ships
mrun-autoname-collides-zsh-random-subshell	back-to-back mrun / tmrun / zjrun without -n NAME produce the same run-<dir>-<hex> suffix; second call errors tmux session 'run-X-NNNN' already exists; zsh -c 'echo $(echo $RANDOM) $(echo $RANDOM)' returns identical numbers	fixed in dot_config/zsh/tools/23_mrun.zsh (read $RANDOM into a parent-shell local before the $(…) boundary)
niri-spawn-cargo-bin-not-on-session-path	niri Mod+T / any spawn "<tool>" opens nothing, no error; binary is in ~/.cargo/bin (works in your shell) but not on the systemd/Wayland session PATH; the ln -s … /usr/local/bin "fix" breaks multi-user	fixed (per-user environment { PATH … } in config.kdl.tmpl, not a system symlink)
npm-postinstall-github-releases-hang	npm install -g hangs after "Downloading https://github.com/.../releases/..."	workaround documented
sudo-shared-setsid-macos	[bootstrap] / [ansible] / [brew] sudo prompts fire 3× in one chezmoi apply on macOS despite "entered once, reused" wording; keepalive.pid points to a dead PID; which setsid → not found	fixed (_sudo_spawn_watchdog falls back to nohup when setsid is absent)
nvim-fs-find-enoent-stale-cwd	nvim 0.12 startup vim/fs.lua:0: ENOENT from avante / lualine / lazy checker; [C]: in function 'assert'	workaround documented (cd to a real dir before launching)
ollama-brew-link-fails-cask-shadows-formula	chezmoi apply aborts at llm_tools : Install Ollama via Homebrew formula with Error: The \brew link` step did not complete successfully/Could not symlink bin/ollama/Target /usr/local/bin/ollama already exists; ollamaformula installed-but-unlinked,shadowed by /usr/local/bin/ollama; the target is a symlink into Ollama.app(caskollama-app); roles after llm_tools` silently skipped	fixed (which ollama pre-check gates the formula install in dot_ansible/roles/llm_tools)
opencode-concurrent-launch-wal-pragma-fails	Failed to run the query 'PRAGMA journal_mode = WAL'; one of N simultaneously-launched opencode TUIs exits on startup (svibe N opencode); log shows several opencode.db opening database within ms	upstream concurrency limit; mitigation = stagger launches (SVIBE_LAUNCH_STAGGER)
opencode-docker-opentui-glibc-loader-missing	docker run ... ghcr.io/anomalyco/opencode exits with Failed to initialize OpenTUI render library: Failed to open library "/tmp/.<hex>-00000001.so": Error loading shared library ld-linux-x86-64.so.2: No such file or directory; image is Alpine/musl, OpenTUI native lib needs glibc	workaround = --entrypoint sh ... -c 'apk add --no-cache gcompat && exec opencode "$@"'; upstream image bug as of 1.15.11
opencode-tool-execution-aborted-on-long-write	OpenCode TUI repeats ~ Preparing write... / Tool execution aborted (sometimes followed by {"type":"api_error","message":"JSON error injected into SSE stream"} and Build · Claude Opus 4.x · interrupted) when the agent tries to write a long file via github-copilot Claude; Claude Code does not reproduce	upstream root cause located 2026-05: post-write side-effects (Effect.orDie on LSP/format/BOM-sync) — PR #26347 ready for review, file may already be on disk despite abort message (verify before retrying); related orphan-tool prefill-400 cascade fixed in v1.15.11
pueue-macos-launchd-not-autostarted-no-socket	macOS pueue / pueue status fails Couldn't find a configuration file. Did you start the daemon yet?, then after brew services start pueue (reports Successfully started) fails one step later I/O error at path ".../Library/Application Support/pueue/pueue_<you>.socket" while connecting to daemon; ps shows no pueued; launchctl list homebrew.mxcl.pueue = "OnDemand" = true + "LastExitStatus" = 0 with NO "PID"; ~/.config/pueue/ doesn't exist (red herring — macOS uses ~/Library/Application Support/pueue/); daemon runs fine by hand (pueued -d)	not a bug — Homebrew formula ships keep_alive false + RunAtLoad-only, launchd doesn't execute pueued after a brew services toggle that coincides with an upgrade/relink; workaround = launchctl kickstart -k gui/$(id -u)/homebrew.mxcl.pueue
raycast-clipboard-sqlcipher-key-not-recoverable	Want to read Raycast clipboard history programmatically; ~/Library/Application Support/com.raycast.macos/raycast-enc.sqlite is SQLCipher (binary contains cipher_* PRAGMAs); security find-generic-password -s Raycast -a database_key -w returns 64-hex; that key fails Parse error: file is not a database (26) for every cipher_compatibility / page_size / raw-vs-KDF combo on every *-enc.sqlite file; older plaintext Clipboard.sqlite schema (ZCLIPBOARDHISTORYITEM) no longer exists	UNSOLVED without RE'ing AppDelegate; workaround = switch to Maccy (open SQLite at ~/Library/Containers/org.p0deje.Maccy/)
tmux-display-menu-silent-fail	prefix + Space / prefix + e doesn't open the popup menu, no error	workaround documented (script + height tiers)
tmux-pane-bottom-blank-alacritty-macos-tabs	inside Alacritty + macOS native tabs when window is maximised (green-button zoom), tmux status bar + a few rows of output paint at the top, then the entire bottom of the window stays empty; tmux display -p '#{pane_height}' reports the full height (e.g. 45); un-maximise / drag corner un-sticks instantly, re-maximise reliably repros; tmux refresh-client does NOT help (redraws using stale cached size); $TERM = tmux-256color (correct, not the cause)	confirmed 2026-05-10 (PTY size desync, maximise-state-specific); workaround = drop Alacritty native tabs / switch to Ghostty
tmux-submenu-flash-and-bottom-right	nested display-menu via run-shell from right-click parent: flash, bottom-right placement, or selection silently does nothing on 2nd open	workaround documented (inline submenu items into parent)
tmux-pane-vanishes-on-ctrl-c-despite-shell-wrapper	tmux pane built with cmd; exec $SHELL wrapper closes on Ctrl+C inside btop/htop/less even though clean quit (q/:q) lands in shell as designed	fixed in dot_config/zsh/tools/22_sesh.zsh (trap '' INT; prefix in _sesh_on_exit_wrap)
tmux-resurrect-agents	tmux-resurrect doesn't restore coding-agent / TUI sessions after kill-server	known limitation
tmux-scrollback-tui-repaint-ghosting	ghost / duplicated lines in tmux scrollback while Claude Code / OpenCode / live progress streams; flipbook frames visible in copy-mode	mitigated (scroll-on-clear off + prefix + [ freeze workflow); fundamental limit
tmux2k-bandwidth-uint64-underflow	18446744073709551615K in tmux status bar	workaround documented
tmuxp-append-ignores-session-start-directory	sesh connect opens repo session but nvim/lazygit/shell all start at $HOME; #{session_path} is correct, #{pane_current_path} is HOME; yaml start_directory silently dead	workaround documented (cd <path> && prefix in sesh.toml startup_command)
tree-sitter-cli-empty-native-binary	:TSInstall <lang> fails with spawn …/tree-sitter-cli/tree-sitter EACCES on every parser; tree-sitter --version still prints a version; native binary is 0 bytes mode 0600	workaround documented (stronger ansible check + rm+reinstall recovery)
tv-channel-bare-braces-break-substitution	TV channel preview shows literal {split:\t:N} instead of substituted values, no error	workaround documented (avoid bare {...} in heredocs; prefer external executable_*.sh/py helpers)
visidata-feather-stringdtype-numpy-dtype	visidata foo.feather exits with ValueError: Could not convert ... Name: <col>, dtype: string to a NumPy dtype (via .dtype value <StringDtype(na_value=<NA>)>) (pandas 3) / Cannot interpret 'string[python]' as a data type (pandas 2); pd.read_feather itself works; status shows raw() returned ERR; only files whose pandas-metadata says numpy_type: string repro	workaround documented (dot_visidatarc reroutes .feather → ArrowSheet; vd-arrow alias as escape hatch); downgrade does NOT help (dtype identity is in the file's schema metadata)
yazi-tmux-popup-crash	Yazi inside display-popup crashes tmux server, "Terminal response timeout"	workaround documented
zoxide-doctor-warning	zoxide: detected a possible configuration issue. / Please ensure that zoxide is initialized right at the end of your shell configuration file (usually ~/.zshrc). / Disable this message by setting _ZO_DOCTOR=0. printed on every prompt; coding-agent bash output mixes warning with unrelated Exit code 2 from build script; agents start prefixing every chezmoi apply with _ZO_DOCTOR=0 defensively	fixed (export _ZO_DOCTOR=0 added to dot_config/shell/20_zoxide.sh)
zsh-insecure-directories-prompt-shared-linuxbrew	new nested zsh blocks on zsh compinit: insecure directories ... Ignore insecure directories and files and continue [y] or abort compinit [n]? then [oh-my-zsh] Insecure completion-dependent directories detected: listing /home/linuxbrew/.linuxbrew/share/zsh* owned by another user; suggested compaudit | xargs chmod g-w,o-w does nothing (perms already 755 — ownership is the failure); fresh login shells clean	fixed (skip_global_compinit=1 in dot_zshenv.tmpl kills Ubuntu's /etc/zsh/zshrc bare compinit prompt + conditional ZSH_DISABLE_COMPFIX=true in dot_zshrc.tmpl when brew prefix isn't ours)
zsh-osc133-precmd-printf-a-not-stored	tmux send-keys -X next-prompt doesn't move cursor even though zsh precmd emits OSC 133 A; C markers from preexec work fine; shell-function cpout/cpcmd/cpblock returns 1 byte	workaround documented (embed A in $PROMPT via %{...%}, not printf from precmd)
zsh-autosuggestions-postdisplay-clobber	custom ZLE widget sets POSTDISPLAY=... + region_highlight then exits; ghost text never renders; add-zle-hook-widget line-pre-redraw shows POSTDISPLAY=[] despite widget setting it microseconds earlier; affects any widget name not prefixed with _ / . / autosuggest-	fixed in dot_config/zsh/tools/05_aisuggest.zsh (ZSH_AUTOSUGGEST_IGNORE_WIDGETS+=(...))
zsh-star-slice-substring-not-element	zsh:1: command not found: o from svibe N opencode; [o exited — back in shell. Re-run with: o]; only the first agent pane broken; agent name truncated to first char; zsh-only (bash fine)	fixed in dot_config/shell/22_sesh.sh (${agents[*]:0:1} → ${agents[@]:0:1})
zsh-tied-array-path-shadowing	command not found only inside one zsh function, works at prompt; hash -r / rehash doesn't help	fixed in dot_config/zsh/tools/22_sesh.zsh (rename local path → target)
tmux-resurrect-agents	reattach restores layout but agent/TUI panes come back as bare shell	workaround documented (@resurrect-processes whitelist)
yazi-tmux-popup-crash	Terminal response timeout from yazi → tmux server dies	workaround documented (use new-window, not display-popup)

Cross-referenced pitfalls (still in their original homes)

These traps are documented elsewhere and aren't duplicated here — the table exists so grepping pitfalls/ still finds them. Move into this folder only if their original location stops being a natural reading flow.

Trap	Lives in	Why not here
chezmoi modify_ files clobbered by chezmoi add	docs/tools/chezmoi-prefixes.md → "Case studies in this repo"	Already part of the prefix-semantics narrative
chezmoi create_ files silently skipped by chezmoi re-add	docs/tools/chezmoi-prefixes.md	Same as above
CodeIsland hook ping-pong with our overlay	docs/tools/agent-overlays.md → "CodeIsland integration"	Documented as part of overlay design
tmux 3.2a display-menu popup off-screen / silently suppressed	AGENTS.md Hard invariant + dot_ansible/roles/devtools/ upgrade logic	Graduated to invariant + ansible mitigation
fleet-apply process substitution + sentinel ordering	AGENTS.md Hard invariant → "fleet-apply semantics"	Graduated to invariant
Sudo session sudo -k invalidates shared cache	AGENTS.md Hard invariant → "Sudo session"	Graduated to invariant
chezmoi modify_settings.json overlay vs Claude live edits	docs/tools/agent-overlays.md	Part of overlay design rationale