From c224595f496607d3b977006a13b4be46d34ab4a7 Mon Sep 17 00:00:00 2001
From: opencode <opencode@local>
Date: Sat, 8 Aug 2026 11:48:16 +0300
Subject: [PATCH] scripts: run_demo.sh launcher (no python on PATH needed),
 friendly port-in-use check in run_bridge.sh; README updated

---
 scripts/run_bridge.sh | 18 ++++++++++++++++++
 scripts/run_demo.sh   |  9 +++++++++
 scripts/setup.sh      |  2 +-
 testbed/README.md     | 23 ++++++++++++++---------
 4 files changed, 42 insertions(+), 10 deletions(-)
 create mode 100755 scripts/run_demo.sh

diff --git a/scripts/run_bridge.sh b/scripts/run_bridge.sh
index 98003d7..36692ca 100755
--- a/scripts/run_bridge.sh
+++ b/scripts/run_bridge.sh
@@ -1,7 +1,25 @@
 #!/usr/bin/env bash
 # Start the AICC capsule testbed bridge over WebSocket (headless).
 # Usage: scripts/run_bridge.sh [port]   (default 8765)
+# Note: the bridge keeps running until interrupted (Ctrl-C).
 set -euo pipefail
 cd "$(dirname "$0")/.."
 PORT="${1:-8765}"
+
+if python3 - "$PORT" <<'EOF'
+import socket, sys
+port = int(sys.argv[1])
+s = socket.socket()
+if s.connect_ex(("127.0.0.1", port)) == 0:
+    print(f"port {port} is already in use")
+    sys.exit(1)
+EOF
+then
+    :
+else
+    echo "error: a bridge may already be running on port $PORT." >&2
+    echo "stop it first, e.g.:  fuser -k ${PORT}/tcp   (or kill the run_bridge.sh process)" >&2
+    exit 1
+fi
+
 exec testbed/.venv/bin/python -m testbed.bridge --host 127.0.0.1 --port "$PORT"
diff --git a/scripts/run_demo.sh b/scripts/run_demo.sh
new file mode 100755
index 0000000..925a366
--- /dev/null
+++ b/scripts/run_demo.sh
@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Run the AICC capsule demo (agent drives the capsule to the beacon).
+# Usage: scripts/run_demo.sh [demo args...]
+#   e.g. scripts/run_demo.sh --agent auto
+#        scripts/run_demo.sh --agent scripted
+#        scripts/run_demo.sh --agent llm --model gemma4:e2b
+set -euo pipefail
+cd "$(dirname "$0")/.."
+exec testbed/.venv/bin/python -m testbed.demo "$@"
diff --git a/scripts/setup.sh b/scripts/setup.sh
index 66c1fb3..ca4d37f 100755
--- a/scripts/setup.sh
+++ b/scripts/setup.sh
@@ -14,5 +14,5 @@ pip install pillow websockets openai pytest pytest-asyncio
 
 echo "Setup done. Activate with: source testbed/.venv/bin/activate"
 echo "Run the bridge:  scripts/run_bridge.sh"
-echo "Run the demo:    testbed/.venv/bin/python -m testbed.demo --agent auto"
+echo "Run the demo:    scripts/run_demo.sh --agent auto"
 echo "Conformance:     testbed/.venv/bin/python -m testbed.conformance ~/Desktop/aicc-spec/conformance/scenarios"
diff --git a/testbed/README.md b/testbed/README.md
index ebeceaf..91a2991 100644
--- a/testbed/README.md
+++ b/testbed/README.md
@@ -27,38 +27,43 @@ over the protocol, no engine hooks.
 
 ```bash
 scripts/setup.sh                 # venv + aicc-py + pillow/websockets/openai
-source testbed/.venv/bin/activate
 ```
 
 The testbed needs the `aicc` SDK installed from `~/Desktop/aicc-py` (the setup
-script does `pip install -e`).
+script does `pip install -e`). The launcher scripts below use the venv
+interpreter directly, so `python` does not need to be on your PATH. To run
+commands by hand instead, activate the venv first:
+`source testbed/.venv/bin/activate`.
 
 ## Run
 
 ```bash
-# 1. Start the bridge (headless)
+# 1. Start the bridge (headless; keep it running in its own terminal)
 scripts/run_bridge.sh            # ws://127.0.0.1:8765
 
 # 2. Run the demo — default `auto` tries the LLM, then hands off to the
 #    scripted agent so the run always completes
-python -m testbed.demo --agent auto
+scripts/run_demo.sh --agent auto
 
 #   scripted only (deterministic, no LLM needed)
-python -m testbed.demo --agent scripted
+scripts/run_demo.sh --agent scripted
 
 #   LLM only (any OpenAI-compatible endpoint; ollama by default)
-python -m testbed.demo --agent llm --model gemma4:e2b
-python -m testbed.demo --agent llm \
+scripts/run_demo.sh --agent llm --model gemma4:e2b
+scripts/run_demo.sh --agent llm \
     --base-url https://api.openai.com/v1 --model gpt-4o-mini --api-key $OPENAI_API_KEY
 ```
 
+If the bridge is already running, `run_bridge.sh` will say so (the port is
+taken); stop the old one with `fuser -k 8765/tcp` or Ctrl-C in its terminal.
+
 The demo prints a full transcript of tool calls/results to stdout and saves the
 capsule's final first-person frame to `demo_final_frame.png`.
 
 ## Conformance
 
 ```bash
-python -m testbed.conformance ~/Desktop/aicc-spec/conformance/scenarios
+testbed/.venv/bin/python -m testbed.conformance ~/Desktop/aicc-spec/conformance/scenarios
 # [PASS] core-01..core-09  ->  9/9 scenarios passed
 ```
 
@@ -112,5 +117,5 @@ asynchronously when `move` hits a wall or crate.
 ## Tests
 
 ```bash
-python -m pytest -q        # 33 tests: physics, renderer, tools, protocol
+testbed/.venv/bin/python -m pytest -q   # 33 tests: physics, renderer, tools, protocol
 ```