chore: share worktree port assignment, document both worktree managers

[hugocasa]

Summary

The per-worktree port slot scan and the .env.local writer were duplicated: once inline in
scripts/worktree-env, once in scripts/post-create.sh. This lifts both into
scripts/worktree-common.sh so every caller shares one implementation, and updates the
AGENTS.md dev environment section to match.

The motivating third caller lives outside this repo. Worktree tooling is being trialled on
herdr alongside the existing setup, and its hooks need the same slot
arithmetic. Sharing the helpers means both paths draw from one port registry (each worktree's
.env.local) and cannot hand out the same slot twice.

No behaviour change for existing callers, and nothing about the webmux setup changes.

Changes

• Add wm_port_in_use, wm_assign_ports and wm_write_env_local to scripts/worktree-common.sh
• scripts/worktree-env: drop the inline slot scan and heredoc, call the helpers
• scripts/post-create.sh: drop the duplicated heredoc, call wm_write_env_local
• wm_assign_ports takes the worktree root as an argument rather than reading the process cwd,
  so it can run from outside the worktree, and prints its slot line to stderr so stdout carries
  only the port pair
• AGENTS.md: the dev environment section assumed webmux and tmux throughout. It now shows the
  detection marker and pane inspection commands for both managers side by side

The AGENTS.md change also corrects a stale pointer. The section sent readers to
webmux/runtime.env on the grounds that .env.local would trip the secret-file read rules. It
does not, only .env does. Since both managers write .env.local through the same helper, it is
the portable source; runtime.env stays documented as the place carrying the extras .env.local
lacks (WEBMUX_*, WM_CLONE_DB, USE_RUST_PLUGIN).

Test plan

• bash -n on all five worktree scripts
• wm_assign_ports on the main checkout returns the lowest free slot, skipping the 28 slots
  already claimed by existing worktrees
• wm_write_env_local writes BACKEND_PORT, FRONTEND_PORT, REMOTE and CARGO_FEATURES
  identically to the previous heredocs
• End-to-end on a scratch worktree: ports assigned, database created and migrated, backend
  served on its assigned port, frontend returned 200 against it
• Verified .env.local is present with the same keys in both a webmux worktree and a herdr
  one, and is readable

---

Summary by cubic

Shares per-worktree port assignment and .env.local writing across worktree tooling, and documents both worktree managers. This prevents slot collisions, keeps webmux, herdr, and repo scripts in sync, and clarifies .env.local as the portable source of per-worktree values.

• Adds wm_port_in_use, wm_assign_ports(<repo_root>), and wm_write_env_local(<repo_root> <backend> <frontend>) in scripts/worktree-common.sh; updates scripts/worktree-env and scripts/post-create.sh to call them. Behavior change: wm_assign_ports requires the worktree root and logs its slot message to stderr; stdout emits only "<backend_port> <frontend_port>".
• Port assignment now reads claimed slots from each worktree’s .env.local and picks the lowest free slot; it warns if the chosen ports are already in use.
• Docs: AGENTS.md now shows detection markers and pane inspect/log commands for both webmux and herdr, points to .env.local as authoritative, keeps webmux’s webmux/runtime.env documented for extras, adds herdr plugin setup (windmill-labs/windmill-herdr, ./setup.sh), and clarifies where WM_CLONE_DB is configured under each manager.

^{Written for commit 1c42763. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying windmill with    Cloudflare Pages

Latest commit:	1c42763
Status:	✅  Deploy successful!
Preview URL:	https://b40bdad8.windmill.pages.dev
Branch Preview URL:	https://share-worktree-port-assignme.windmill.pages.dev

View logs