/pr-worktree

name: pr-worktree
description: >
  Create and tear down the throwaway git worktrees used to test community PRs
  for waku-agent, without leaking API keys or leaving branches behind. Use when
  setting up to test a PR, and ALWAYS after a PR is merged, closed, or parked.

Throwaway worktrees for PR testing

Testing a contributor's PR must never disturb the live dashboard on 7777, and it must never leave a second copy of Sean's API keys on disk. Both have happened.

Setting one up

REPO=$(git rev-parse --show-toplevel)
N=<pr-number>
git -C $REPO fetch -q origin pull/$N/head:pr-$N
git -C $REPO worktree add -q ~/Developer/waku-prs/pr$N pr-$N
ln -sfn $REPO/.waku ~/Developer/waku-prs/pr$N/.waku   # real memory/traces/calendar

Never `gh pr checkout` — it switches the branch of the main working tree, and the live dashboard runs from there.

Only link `.env` when the test actually needs keys

Deterministic evals do not. Skip the symlink for a test-only pass, so untrusted contributor code never runs against real credentials. Link it only after you have read the diff:

ln -sfn $REPO/.env ~/Developer/waku-prs/pr$N/.env

The symlink trap (this cost us a full copy of every key)

`python-dotenv`'s `set_key` — which the dashboard's Save & switch calls — **replaces a symlinked `.env` with a regular file**. The moment anyone saves a setting from a PR worktree's dashboard, that worktree gains a complete copy of every key in the real `.env`: Anthropic, OpenAI, Gemini, Moonshot, xAI, Zhipu, Tavily, Telegram, Discord.

So: after any test that saved settings, assume the `.env` is a real file and **check before deleting the worktree**, then move anything worth keeping into the main `.env` rather than losing it.

[ -L ~/Developer/waku-prs/pr$N/.env ] && echo "symlink (safe)" || echo "REAL FILE — copy of all keys"

New env vars a PR introduces belong in the **main** `.env`, not the worktree's. Copy the values across without printing them, and leave switches that would change what the live demo shows (e.g. `WAKU_EPISODIC_STORE`) on their old value — Sean films against the local data.

Running its dashboard

Always a second port, so 7777 stays untouched:

cd ~/Developer/waku-prs/pr$N
WAKU_DASHBOARD_PORT=7778 $REPO/.venv/bin/python -m waku.ops.dashboard

Optional extras a PR needs (`[notion]`, `[discord]`, …) install with `uv`, since the venv has no `pip`:

uv pip install --python $REPO/.venv/bin/python "<package>"

Tearing it down — do this the same turn the PR is decided

A worktree is finished the moment the PR is merged, closed, or parked waiting on the contributor. Leaving it costs disk, confuses future greps, and may be sitting on a copy of every key.

REPO=$(git rev-parse --show-toplevel)
# 1. rescue any new env vars into the MAIN .env first (see above)
# 2. stop anything still running from it
lsof -ti:7778 | xargs kill -9 2>/dev/null
# 3. remove worktrees + their local branches
for d in ~/Developer/waku-prs/*/; do git -C $REPO worktree remove --force "$d"; done
git -C $REPO worktree prune
git -C $REPO branch --list 'pr-*' | tr -d ' ' | xargs -r -n1 git -C $REPO branch -D
# 4. verify nothing is left holding keys
find ~/Developer/waku-prs -name ".env" 2>/dev/null

That `find` must print nothing. If it prints a path, the key copy is still there.

Checklist before you say a PR is done

• [ ] new env vars moved into the main `.env`
• [ ] `find ~/Developer/waku-prs -name ".env"` prints nothing
• [ ] `git worktree list` shows only the main tree
• [ ] no `pr-*` branches left
• [ ] nothing still listening on 7778
• [ ] settings the test changed are back where the live demo expects them

Related: [[review-pr]] for how to review and present the PR itself.