fix(install): wb.upgrade brick — symlink corruption + zsh $path clobber

[amit-t]

Summary

Two install/upgrade bugs surfaced during the v1.1.0 real-LLM smoke against wb-gitlore. Together they made every wb.upgrade a no-op that wrongly reported a clean workbench as dirty and forwarded into a deleted worktree path. Both reproducible on macOS+zsh.

Bug 1 — install.zsh corrupts update.zsh via legacy symlink

install.zsh:142 does:

cat > "$BIN_DIR/update.wb" <<SH
...
SH

Earlier install.zsh versions installed update.wb as a symlink (~/.local/bin/update.wb → update-workbench/update.zsh). The new cat > follows that symlink and overwrites the real update.zsh with the 3-line deprecation shim. Every re-install re-corrupts the clone:

#!/usr/bin/env zsh
print -u2 -r -- "[deprecated] use 'wb.upgrade'. Forwarding..."
exec "/.../.claude/worktrees/feat+repo-context-scan/update-workbench/update.zsh" "$@"

(The hard-coded worktree path is whatever $SCRIPT_DIR was the first time cat > ran, frequently a long-deleted feature worktree.)

Fix: rm -f "$DEPRECATED_SHIM" before the heredoc so any legacy symlink is severed first.

Bug 2 — update.zsh clobbers $PATH via zsh $path special parameter

update-workbench/update.zsh:146 does while IFS= read -r path; do ... done. In zsh, the lowercase $path is a tied array that mirrors $PATH. Reading the first template path into path rewrites PATH to that value (e.g. CLAUDE.md). Every subsequent git call in the loop hits "command not found" (exit 127), so git diff --quiet returns non-zero and every template-owned path is falsely flagged as dirty:

Uncommitted changes on template-owned paths:
  CLAUDE.md
  AGENTS.md
  ...
  tests/**
Commit or stash them, or open a PR upstream for the improvements, then retry.

The user is told to commit changes that don't exist.

Fix: rename the loop variable from path to tpl_path in all three while-loops (dirty check, dry-run diff stat, apply). Drop a one-line note in the dirty-check block so the next reader doesn't trip over the same gotcha.

Regression tests

• tests/test-install-update-wb-symlink-safe.zsh — sets up a fake HOME with the legacy update.wb symlink, runs install.zsh, and asserts the real update.zsh is byte-identical afterwards (shasum compare) and that the new shim is a regular file, not a symlink.
• tests/test-update-zsh-path-clobber.zsh — drives update.zsh --dry-run against a fresh stamped workbench built from tests/fixtures/bare-upstream/setup.sh, with one clean template-owned path (version.json). Asserts the dirty-check does not falsely flag the path and --dry-run reaches the diff stage.

Both tests were verified red against the unfixed code and green after the fixes. tests/run-all.zsh picks them up automatically.

Test plan

• CI green (shell-lint + tests)
• After merge + release: wb.upgrade from a stamped wb correctly detects a clean tree, pulls template-owned paths, and stamps .workbench-state/template-version.json
• install.zsh re-run on a host with the legacy symlink does not corrupt update.zsh (test catches this)

Risk

Low. Both fixes are surgical, with regression tests. The tpl_path rename does not change any external interface. The rm -f before cat > is a no-op if the path didn't already exist.

🤖 Generated with Claude Code