A session in a git worktree finds no game, no Ghidra export and no Python environment

Symptoms

An agent session started in a git worktree (a parallel session, or a tool that makes one for each task) cannot find game/, analysis/export/, derived/, .venv or .env. The setup hook asks for scripts/setup.sh. A tool that worked in the main checkout fails with a missing file. When several sessions run ghidra-run.sh at once, all but one stop with Ghidra's Unable to lock project (a LockException).

Cause

A worktree holds the tracked files only. The game, the Ghidra project and export, the emulator's output and the Python environment are ignored by git on purpose, so a new worktree has none of them (observed, Hardwar's four parallel sessions). Ghidra locks a project while a headless job runs in it, and ghidra-run.sh uses one project, analysis/ghidra-project.

What to do

A project whose folders live in the GameFrame home links them into the worktree with one command. The links are ignored, and the shared Python is in the home's python/:

./gameframe game link ID .

An older project with real folders in the main checkout links them by hand (the links are ignored too), or moves them into the home once with ./gameframe home adopt:

MAIN=$(git worktree list | head -1 | awk '{print $1}')
for d in target analysis derived .venv; do [ -e "$d" ] || ln -s "$MAIN/$d" "$d"; done
[ -e .env ] || cp "$MAIN/.env" .env

Write new ground truth and notes into the main checkout's folders through the links, so other sessions see them. Do not stage the links (git add path, never git add -A).

Run one Ghidra job at a time per project. Sessions that need Ghidra together take turns, or each copies the project first and passes --project DIR to ghidra-run.sh (a copy does not see labels applied to the original later). Read the export's text files freely: only the headless job takes the lock.