Coordinate workspace launcher port allocation

Author: RichardGeorgeDavis

README.md

@@ -89,7 +89,7 @@ If you want the fuller workspace path after that:
 - Use [docs/20-ai-context-side-load.md](docs/20-ai-context-side-load.md) for the generated AI side-load contract and the `generate-context-cache.sh` workflow.
 - Use [docs/09-new-repo-baseline.md](docs/09-new-repo-baseline.md) when adding or onboarding a repo.
 
-Repo-specific launchers can also live under `tools/local/commands/`. For example, `tools/local/commands/Run Knowledge Palace UI.command` starts the Knowledge Palace local web UI from the workspace root.
+Repo-specific launchers can also live under `tools/local/commands/`. Those workspace launchers should keep the host on `127.0.0.1`, prefer a repo-specific port range, and step to the next free port instead of randomizing the address. For example, `tools/local/commands/Run Knowledge Palace UI.command` starts the Knowledge Palace local web UI from the workspace root.
 
 ## How To Contribute
 

docs/09-new-repo-baseline.md

@@ -11,6 +11,7 @@ This is not meant to force every repo into one shape. The goal is to keep each r
 - Use shared caches under workspace `cache/` where that helps, but keep installs local to the repo.
 - Do not make a reverse-proxy or mapped-host layer mandatory unless the repo genuinely needs that behaviour.
 - Prefer the repo's native runtime and package manager.
+- For workspace launchers, keep the host stable on `127.0.0.1` and prefer a repo-specific port range that can step to the next open port instead of randomizing addresses.
 
 ## Default runtime expectations
 

docs/CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## 2026-04-17
 
+- Added `tools/scripts/workspace-port-allocator.sh` and rewired the workspace-level launchers under `tools/local/commands/` to reserve ports through `cache/runtime/ports/`, reducing same-time launcher collisions while keeping hosts fixed on `127.0.0.1` and falling forward to the next open port in each repo's range.
 - Installed `httrack` for this workspace environment and added `tools/scripts/capture-site-reference.sh` as the repo-intake wrapper for public-site reference copies, with dry-run-by-default behavior, conservative same-domain defaults, and repo-local capture notes under `ref/httrack/`.
 - Updated the public repo-intake surfaces in [README](../README.md), [docs/README](README.md), [09-new-repo-baseline](09-new-repo-baseline.md), and [tools/templates/repo-docs/README.site-reference.template.md](../tools/templates/repo-docs/README.site-reference.template.md) so site-reference repos have one documented `httrack` path.
 

docs/HANDOVER.md

@@ -65,6 +65,7 @@ The workspace foundation is in place and released as a stable baseline:
 - MemPalace is now integrated as the first core workspace service under `tools/mempalace` with user-scoped durable state under `shared/mempalace/<user>/`
 - installable abilities and core services are now tracked in `tools/manifests/workspace-capabilities.json`
 - optional abilities live under `repos/abilities/` rather than the normal repo-group update path
+- workspace-level launchers under `tools/local/commands/` now coordinate port reservations through `cache/runtime/ports/`, so concurrent launches keep `127.0.0.1` stable and step forward inside each repo's local port range instead of racing on the same candidate port
 
 ## Current source taxonomy
 
@@ -146,6 +147,18 @@ The tracked helper surfaces for this flow now live at:
 - `tools/scripts/capture-site-reference.sh`
 - `tools/templates/repo-docs/README.site-reference.template.md`
 
+## Launcher port allocation note (2026-04-17)
+
+The workspace launcher baseline is now:
+
+- keep local launcher hosts on `127.0.0.1`
+- prefer a repo-specific port range over a random address
+- reserve ports through `tools/scripts/workspace-port-allocator.sh`
+- store transient reservations under `cache/runtime/ports/`
+- let launchers move to the next open port, or the next open web/api pair for Workspace Hub
+
+This is intended to reduce same-time launcher collisions without making local URLs unpredictable.
+
 ## Release verification status
 
 The stable release gate has already been exercised successfully:

docs/README.md

@@ -87,6 +87,7 @@ Useful maintenance scripts:
 - `tools/scripts/manage-workspace-capabilities.sh` lists, installs, updates, enables, disables, or uninstalls tracked workspace abilities and core services, with dry-run mode by default.
 - `tools/scripts/update-github-refs.sh` remains the compatibility wrapper for update-only reviewed GitHub-ref flows and delegates to the capability lifecycle command.
 - `tools/scripts/capture-site-reference.sh` previews or runs an `httrack` capture for a public-site reference repo, using conservative same-domain defaults and writing capture notes under repo-local `ref/httrack/`.
+- `tools/scripts/workspace-port-allocator.sh` centralizes workspace launcher port reservations under `cache/runtime/ports/`, so concurrent launchers can keep `127.0.0.1` stable and step to the next open port without colliding.
 - `tools/scripts/use-design-md.sh` mirrors the managed VoltAgent `DESIGN.md` catalog ability into `cache/design-md/catalog/`, lists available site ids, and can copy a selected `DESIGN.md` into a repo root.
 - `tools/scripts/sync-reference-snapshots.sh` previews or refreshes ignored upstream reference snapshots under `tools/ref/`, with dry-run mode by default.
 - `tools/scripts/sync-codex-skills.sh` previews or syncs tracked workspace skill sources into repo `.codex/skills/` folders plus optional `.agents/skills/` compatibility mirrors, with dry-run mode by default.

repos/workspace-hub/README.md

@@ -172,6 +172,14 @@ pnpm build
 pnpm preview
 ```
 
+Workspace-level local launcher:
+
+```bash
+tools/local/commands/Run\ Workspace\ Hub.command
+```
+
+That launcher keeps the host on `127.0.0.1`, chooses the next free web and API port pair in the configured range, and opens the browser once the app responds.
+
 To generate the workspace-side AI summaries that the repo-details panel can inspect, run from the workspace root:
 
 ```bash

repos/workspace-hub/vite.config.ts

@@ -1,6 +1,8 @@
 import { defineConfig } from 'vite'
 import react from '@vitejs/plugin-react'
 
+const apiPort = Number(process.env.WORKSPACE_HUB_API_PORT ?? '4101')
+
 // https://vite.dev/config/
 export default defineConfig({
   plugins: [react()],
@@ -9,7 +11,7 @@ export default defineConfig({
     port: 4100,
     strictPort: true,
     proxy: {
-      '/api': 'http://127.0.0.1:4101',
+      '/api': `http://127.0.0.1:${apiPort}`,
     },
   },
   preview: {

tools/local/commands/Run Knowledge Palace UI.command

@@ -5,7 +5,9 @@ set -euo pipefail
 SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd)"
 WORKSPACE_ROOT="$(cd -- "$SCRIPT_DIR/../../.." && pwd)"
 PROJECT_DIR="$WORKSPACE_ROOT/repos/current-builds/knowledge-palace"
-URL="${KNOWLEDGE_PALACE_UI_URL:-http://127.0.0.1:8765}"
+HOST="127.0.0.1"
+START_PORT="${KNOWLEDGE_PALACE_UI_PORT:-8765}"
+MAX_PORT="${KNOWLEDGE_PALACE_UI_MAX_PORT:-8799}"
 
 if [[ ! -d "$PROJECT_DIR" ]]; then
   echo "Knowledge Palace repo not found:"
@@ -16,6 +18,7 @@ if [[ ! -d "$PROJECT_DIR" ]]; then
 fi
 
 cd "$PROJECT_DIR"
+source "$WORKSPACE_ROOT/tools/scripts/workspace-port-allocator.sh"
 
 if ! python3 - <<'PY' >/dev/null 2>&1
 import importlib
@@ -30,16 +33,24 @@ then
   echo
 fi
 
+PORT="$(workspace_reserve_port "$START_PORT" "$MAX_PORT")" || {
+  echo "No free port found between $START_PORT and $MAX_PORT."
+  exit 1
+}
+
+URL="http://${HOST}:${PORT}/"
+
 echo "Starting Knowledge Palace UI"
 echo "Project dir: $PROJECT_DIR"
 echo "URL: $URL"
 echo
 
-python3 -m knowledge_palace.cli serve-ui &
+python3 -m knowledge_palace.cli serve-ui --host "$HOST" --port "$PORT" &
 SERVER_PID=$!
 
 cleanup() {
   kill "$SERVER_PID" 2>/dev/null || true
+  workspace_release_port_reservations || true
 }
 
 trap cleanup EXIT INT TERM

tools/local/commands/Run THREE.MeshLine.command

@@ -0,0 +1,49 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd)"
+WORKSPACE_ROOT="$(cd -- "$SCRIPT_DIR/../../.." && pwd)"
+PROJECT_DIR="$WORKSPACE_ROOT/repos/prototypes/THREE.MeshLine"
+HOST="127.0.0.1"
+START_PORT="${THREE_MESHLINE_PORT:-4176}"
+MAX_PORT="${THREE_MESHLINE_MAX_PORT:-4199}"
+
+if [[ ! -d "$PROJECT_DIR" ]]; then
+  echo "Project not found:"
+  echo "  $PROJECT_DIR"
+  echo
+  read '?Press Return to close this window...'
+  exit 1
+fi
+
+cd "$PROJECT_DIR"
+source "$WORKSPACE_ROOT/tools/scripts/workspace-port-allocator.sh"
+
+PORT="$(workspace_reserve_port "$START_PORT" "$MAX_PORT")" || {
+  echo "No free port found between $START_PORT and $MAX_PORT."
+  exit 1
+}
+
+URL="http://${HOST}:${PORT}/demo/index.html"
+
+python3 -m http.server "$PORT" --bind "$HOST" &
+SERVER_PID=$!
+
+cleanup() {
+  kill "$SERVER_PID" 2>/dev/null || true
+  workspace_release_port_reservations || true
+}
+
+trap cleanup EXIT INT TERM
+
+until curl -sSf "$URL" >/dev/null 2>&1; do
+  if ! kill -0 "$SERVER_PID" >/dev/null 2>&1; then
+    wait "$SERVER_PID"
+    exit $?
+  fi
+  sleep 1
+done
+
+open "$URL"
+wait "$SERVER_PID"

tools/local/commands/Run Twisted-Colorful-Spheres-WebGLBlobs.command

@@ -0,0 +1,49 @@
+#!/bin/zsh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd -- "$(dirname -- "$0")" && pwd)"
+WORKSPACE_ROOT="$(cd -- "$SCRIPT_DIR/../../.." && pwd)"
+PROJECT_DIR="$WORKSPACE_ROOT/repos/prototypes/Twisted-Colorful-Spheres-WebGLBlobs"
+HOST="127.0.0.1"
+START_PORT="${WEBGLBLOBS_PORT:-4176}"
+MAX_PORT="${WEBGLBLOBS_MAX_PORT:-4199}"
+
+if [[ ! -d "$PROJECT_DIR" ]]; then
+  echo "Project not found:"
+  echo "  $PROJECT_DIR"
+  echo
+  read '?Press Return to close this window...'
+  exit 1
+fi
+
+cd "$PROJECT_DIR"
+source "$WORKSPACE_ROOT/tools/scripts/workspace-port-allocator.sh"
+
+PORT="$(workspace_reserve_port "$START_PORT" "$MAX_PORT")" || {
+  echo "No free port found between $START_PORT and $MAX_PORT."
+  exit 1
+}
+
+URL="http://${HOST}:${PORT}/"
+
+npm start -- --port "$PORT" &
+SERVER_PID=$!
+
+cleanup() {
+  kill "$SERVER_PID" 2>/dev/null || true
+  workspace_release_port_reservations || true
+}
+
+trap cleanup EXIT INT TERM
+
+until curl -sSf "$URL" >/dev/null 2>&1; do
+  if ! kill -0 "$SERVER_PID" >/dev/null 2>&1; then
+    wait "$SERVER_PID"
+    exit $?
+  fi
+  sleep 1
+done
+
+open "$URL"
+wait "$SERVER_PID"