Document and gate worktree seed provenance, 0700 default path

[DROOdotFOO]

Summary

Hardens scripts/worktree.sh so cache seeding cannot silently cross trust or filesystem boundaries.

• Reject option-like --from values and resolve revisions to commit OIDs before directory creation.
• Atomically claim explicit destinations at mode 0700; default paths remain private mktemp directories.
• Fall back to /tmp when TMPDIR is empty, invalid, or /.
• Compare root/package mix.exs and mix.lock provenance.
• Reject symlinked manifests, package paths, and cache destinations.
• Serialize each target's seed operation with a private git-dir lock.
• Treat the complete seed as one transaction; rollback all replaced caches in reverse order on errors or signals.
• Verify directory identity and repository provenance before recursive failed-add cleanup; preserve and report residue when cleanup cannot be proved safe.
• Keep usage errors concise while preserving full explicit help.
• Update tracked docs to match the implemented guarantees.

Manual testing

• bash -n scripts/worktree.sh
• Actual add --fresh / rm smoke completed and cleaned its branch/path
• Leading-dash --from was rejected before path creation
• Failed-add residue check confirmed no requested path remained
• Transaction, signal rollback, lock contention, symlink, manifest-drift, and TMPDIR=/ smokes were exercised during implementation

[github-actions]

Unified Regression Test Results

Workflow: Unified Regression Testing
Event: pull_request
SHA: e47836a

Performance Results

Found 1 performance result(s)

Memory Results

Found 3 memory result(s)

Targets

• Parser: <3μs average
• Render: <1ms average
• Memory: <3MB per session

[DROOdotFOO]

Adversarial Review: PR #1037 (worktree-provenance)

Three personas ran independently (Saboteur, New Hire, Security Auditor), all three driving the branch's script against scratch repos in /tmp.

CRITICAL

• A symlinked packages/<pkg> in the branch under review makes the seed delete and overwrite arbitrary directories. [Security Auditor + Saboteur -> promoted from HIGH] seed_caches globs packages/*/deps and packages/*/_build in the TARGET worktree and replace_dirs through them. Reproduced in a scratch repo: a branch committing packages/foo as a symlink to /tmp/wtaudit/victim -> worktree.sh add evil ... exits 0, prints "seeded ... (root + 1 package(s))", and victim/_build/canary.txt is GONE, with victim/_build and victim/deps replaced by the source's caches. Aimed at the source checkout itself (packages/foo -> /tmp/wtaudit2/src) it deleted the SOURCE's _build/ROOTMARKER. The exact use case this PR's own header calls out — "a worktree created to review someone else's branch" — is the attack. The fix is cheap: [[ -L "$target/packages/$p" ]] && skip, or resolve each package dir with -P and refuse anything outside $target.

HIGH

• The lock gate is defeated by the branch it gates. [Security Auditor] cmp -s and -f follow symlinks, so a branch committing mix.lock as a symlink to the source checkout's own lock compares the file to itself and passes (worktree.sh:209). Verified, exit 0. Same class as the finding above: branch-controlled filesystem shapes are not defended anywhere in the seed path.
• git worktree add failing AFTER checkout leaves a populated, registered, unseeded worktree plus a stray branch. [Saboteur] The new unwind is rmdir with failures swallowed (:349-352). Reproduced with a core.hooksPath post-checkout that exits 1: git materialises and registers the worktree, the hook fails, rmdir fails silently, the script prints nothing and exits 1, leaving deps=NO _build=NO — precisely the unseeded worktree the adjacent comment says must never exist. Separately, git worktree add -b creates the branch before materialising, so even a pre-checkout failure (read-only parent, exit 128) leaks the branch, and re-running then fails with the misleading "already exists; --from would be ignored".
• sync inherits the exit-3 gate with no escape hatch. [Saboteur + New Hire -> promoted from MEDIUM] assert_locks_match lives inside seed_caches, which cmd_sync also calls — so the one command whose whole purpose is "re-seed after a dependency bump in this checkout" now refuses exactly that case, and the remedy it prints (add --fresh) means destroy and recreate the worktree. Worse, cmd_sync parses no flags: sync <path> --fresh silently seeds and exits 0, the opposite of what was asked, while add rejects unknown options.

MEDIUM

• The comment justifying the gate says "Mix will not notice" a lock mismatch; a scratch mix compile with a mismatched lock shows Mix does notice [Saboteur].
• The refusal message names a target directory that is deleted milliseconds later, does not say which side is ahead, and gives backwards advice for its most likely trigger (an uncommitted mix.lock in the source checkout) [New Hire].
• The explicit-path [[ -e || -L ]] check is check-then-use; the header's "still refused if anything is already there" reads as a guarantee and is best-effort [Security Auditor].

LOW

• The unwind claims it deleted a branch it did not delete when the branch pre-existed [Saboteur + New Hire -> promoted to MEDIUM].
• --help mentions neither the trust boundary nor --fresh's cold-build cost [New Hire]; scripts/README.md still describes the old behaviour [New Hire]; a branch name starting with - is not rejected [Saboteur]; the lock-path dedupe uses a string scan where an associative array is clearer [New Hire]; CLAUDE.md:143 omits the "staleness, not integrity" caveat the script header states correctly [Security Auditor].

Verified negatives

shellcheck 0.11.0 and bash -n clean. mktemp default path: 0700, unguessable, correct under TMPDIR unset / trailing slash / spaces / nonexistent / read-only. Four concurrent add invocations and a same-branch race unwound correctly. cp -R does not dereference tree symlinks on either BSD or GNU, and the repo's 109 _build symlinks are all relative — the seed plants no links back into the source. --fresh really does avoid the caches, and the Hex tarball cache it falls back on IS checksum-verified (sha256 of the cached jason-1.4.5.tar equals the mix.lock entry). The tamper probe confirms the header's "staleness check, not an integrity one" paragraph is exactly right. Nothing in the script executes branch-controlled content (core.hooksPath is source-side; no post-checkout hook present).

Cross-persona overlaps

Issue	Personas	Promotion
Branch-controlled symlink in packages/*	Security Auditor, Saboteur	HIGH -> CRITICAL
sync + exit 3 + ignored --fresh	Saboteur, New Hire	MEDIUM -> HIGH
Unwind message lies about the branch	Saboteur, New Hire	LOW -> MEDIUM

Verdict: BLOCK

Before merge: refuse symlinked packages/* entries and a symlinked mix.lock in the target (both are one-line guards and both defeat the feature this PR advertises); complete the unwind with git worktree remove --force plus a tried_branch marker; either exempt sync from the lock gate or give it a real flag parser and a sync-shaped remedy.