feat(local-dev): deploy from a sibling git worktree via up --worktree/--branch

[Yicong-Huang]

What changes were proposed in this PR?

bin/local-dev.sh can now build and run the stack from a sibling git worktree while the orchestration tooling itself always runs from the canonical checkout.

The key split is SELF_ROOT (where local-dev.sh, tui.py, and the docker overlay live — the tooling) vs SOURCE_ROOT (the application tree that gets built/run, which REPO_ROOT now points at).

• up / auto accept --worktree=PATH or --branch=NAME (resolved to the worktree that has the branch checked out). A plain up returns to this checkout.
• The selection persists to $STATE_DIR/deploy-source, so status / down / logs / single-service rebuild / auto all act on the active deployment. up re-marks the deploy target (branch / sha / worktree) at startup, and status --json gains "worktree" and "source" fields.
• Build stamps are namespaced per source tree (sha1 of the absolute path), so switching worktrees can't let a stamp from tree A suppress the required first build of tree B.
• Infra docker compose / .env / overlay stay pinned to the canonical checkout (orchestration), while the app schema/DDL still comes from the deployed source.
• The interactive TUI mirrors the CLI: u / a accept the same selectors, and the banner + SRC-dirty column re-point to the active tree live (the shell exports TEXERA_DEPLOY_SOURCE; the TUI re-reads the persisted pointer after a switch).
• Invalid --branch / --worktree fail fast with a clear, actionable message before anything is built or started.

Any related issues, documentation, discussions?

Closes #6030. The --help text and the in-TUI help (h) document the new selectors.

How was this PR tested?

Extended both existing local-dev test suites (all green):

• bin/local-dev/tests/test_local_dev_sh.sh — 25 checks (6 new): --help documents the selectors; status --json carries worktree/source; a stale pointer is dropped and falls back to self; a valid pointer to a throwaway worktree (created and cleaned up in-test) is honored and reports its branch; invalid --branch and --worktree fail fast with rc=1.
• bin/local-dev/tests/test_local_dev_tui.py — 43 checks (5 new): _stamp_dir_for matches the shell's sha1(path)[:12] namespacing; _resolve_deploy_source returns self when the pointer is missing/stale/points at a non-checkout, and the worktree when valid.

Run:

bash bin/local-dev/tests/test_local_dev_sh.sh
python3 -m pytest bin/local-dev/tests/test_local_dev_tui.py -q

Also verified manually that status --json against a persisted worktree pointer reports that worktree's branch/sha/source, and that bash -n / py_compile pass.

Was this PR authored or co-authored using generative AI tooling?

Generated-by: Claude Opus 4.8 (Claude Code)

[github-actions]

Automated Reviewer Suggestions

Based on the git blame history of the changed files, we recommend the following reviewers:

• No candidates found from git blame history.

[Copilot]

Copilot wasn't able to review any files in this pull request.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Copilot wasn't able to review any files in this pull request.