Dataface Tasks

Add per-worktree local port bundles for dispatch QA

IDINFRA_TOOLING-ADD_PER_WORKTREE_LOCAL_PORT_BUNDLES_FOR_DISPATCH_QA
Statuscompleted
Priorityp1
Milestonem1-ft-analytics-analyst-pilot
Ownersr-engineer-architect
Completed bydave
Completed2026-03-18

Problem

Allocate unique local serve ports for each dispatched worktree, write a worktree-local ports file similar to .cbox-ports.json, and teach local serve/QA workflows to read it so parallel worktrees can run QA without port collisions.

Context

Possible Solutions

  • Recommended: allocate a gitignored .worktree-ports.json during scripts/worktree-new, then teach just worktree-serve, just worktree-restart-serve, scripts/dispatch, and qa-explorer docs to consume the same manifest. This keeps the port source of truth in one file and mirrors the old cbox flow without introducing container-only assumptions.

Plan

  1. Add a small stdlib-only scripts/worktree_ports.py allocator that chooses the first free 100-port offset bundle and writes .worktree-ports.json.
  2. Update scripts/worktree-new and scripts/dispatch to generate/read the manifest and surface the worktree Cloud URL.
  3. Add just worktree-serve and just worktree-restart-serve, plus worktree-specific health checks.
  4. Update QA/task/PR docs to use the worktree-local manifest and keep markdown changes included in PRs.
  5. Cover the new script path with focused script tests.

Implementation Progress

  • Added scripts/worktree_ports.py with allocation, shell export, and value lookup commands.
  • scripts/worktree-new now writes .worktree-ports.json and prints the Cloud URL for the new worktree.
  • scripts/dispatch now records cloud_url and ports_file in its status/log output so QA can discover the right stack.
  • Added just worktree-serve / just worktree-restart-serve and check_local_stack.py worktree.
  • Updated qa-explorer, task-manager, AGENTS.md, and PR workflow docs to use the worktree manifest and to always include markdown changes in PRs.
  • Added script regressions for worktree port allocation, shell export formatting, worktree-new, and dispatch.

QA Exploration

N/A. This is local-dev/worktree infrastructure, not a browser-facing product flow.

  • [x] QA exploration completed (or N/A for non-UI tasks)

Review Feedback

  • Added a defensive No usable project found guard in org chat scope resolution.
  • Hardened emit_shell_exports() to use single-quoted shell values before eval.
  • Removed the temporary scripts/__init__.py package marker after it broke temp-repo PR script tests.

  • [x] Review cleared