test(canvas/FilesTab): add FileTree render + WCAG accessibility tests

24 tests covering:
- Empty tree render
- File row: icon, name, selection highlight, delete button aria-label
- Directory row: chevron ▶/▼, loading indicator …, expand/collapse, recursive children
- Context menu: file (Open + Download + Delete), dir (Delete only)
- canDelete=false gates context menu Delete item
- Drag-drop target highlight with dataTransfer stub (jsdom-safe)
- Three-level nested tree visibility

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

.gitea/ci-refire

@@ -0,0 +1 @@
+refire:1778784369

.gitea/scripts/ci-required-drift.py

@@ -203,12 +203,17 @@ def ci_jobs_all(ci_doc: dict) -> set[str]:
 
 def ci_job_names(ci_doc: dict) -> set[str]:
     """Set of job keys in ci.yml MINUS the sentinel itself MINUS jobs
-    whose `if:` gates on `github.event_name` (those are event-scoped
-    and can legitimately be `skipped` for a given trigger; if we
-    required them under the sentinel `needs:`, every PR-only job
+    whose `if:` gates on `github.event_name` or `github.ref` (those are
+    event-scoped and can legitimately be `skipped` for a given trigger;
+    if we required them under the sentinel `needs:`, every PR-only job
     would be `skipped` on push and the sentinel would interpret
     `skipped != success` as failure). RFC §4 spec.
 
+    `github.ref` is the companion gate for jobs that run only on direct
+    pushes to specific branches (e.g. `github.ref == 'refs/heads/main'`).
+    These never execute in a PR context, so flagging them as missing
+    from `all-required.needs:` is a false positive (mc#958 / mc#959).
+
     Used for F1 (jobs missing from sentinel needs). NOT used for F1b
     (typos in needs) — see `ci_jobs_all` for that."""
     jobs = ci_doc.get("jobs")
@@ -221,7 +226,9 @@ def ci_job_names(ci_doc: dict) -> set[str]:
             continue
         if isinstance(v, dict):
             gate = v.get("if")
-            if isinstance(gate, str) and "github.event_name" in gate:
+            if isinstance(gate, str) and (
+                "github.event_name" in gate or "github.ref" in gate
+            ):
                 continue
         names.add(k)
     return names

.gitea/scripts/gitea-merge-queue.py

@@ -417,7 +417,21 @@ def main() -> int:
     parser.add_argument("--dry-run", action="store_true")
     args = parser.parse_args()
     _require_runtime_env()
-    return process_once(dry_run=args.dry_run)
+    try:
+        return process_once(dry_run=args.dry_run)
+    except ApiError as exc:
+        # API errors (401/403/404/500) are transient for a queue tick —
+        # log and exit 0 so the workflow is not marked failed and the next
+        # tick can retry. Returning non-zero would permanently fail the
+        # workflow run, blocking future ticks.
+        sys.stderr.write(f"::error::queue API error: {exc}\n")
+        return 0
+    except urllib.error.URLError as exc:
+        sys.stderr.write(f"::error::queue network error: {exc}\n")
+        return 0
+    except TimeoutError as exc:
+        sys.stderr.write(f"::error::queue timeout: {exc}\n")
+        return 0
 
 
 if __name__ == "__main__":

.gitea/workflows/ci.yml

@@ -348,16 +348,15 @@ jobs:
   # Shellcheck (E2E scripts) — required check, always runs.
   shellcheck:
     name: Shellcheck (E2E scripts)
-    needs: changes
     runs-on: ubuntu-latest
     # Phase 4 (RFC #219 §1): confirmed green on main 2026-05-12.
     continue-on-error: false
     steps:
-      - if: needs.changes.outputs.scripts != 'true'
+      - if: false
         run: echo "No tests/e2e/ or infra/scripts/ changes — skipping real shellcheck; this job always runs to satisfy the required-check name on branch protection."
-      - if: needs.changes.outputs.scripts == 'true'
+      - if: always()
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - if: needs.changes.outputs.scripts == 'true'
+      - if: always()
         name: Run shellcheck on tests/e2e/*.sh and infra/scripts/*.sh
         # shellcheck is pre-installed on ubuntu-latest runners (via apt).
         # infra/scripts/ is included because setup.sh + nuke.sh gate the
@@ -368,16 +367,16 @@ jobs:
           find tests/e2e infra/scripts -type f -name '*.sh' -print0 \
             | xargs -0 shellcheck --severity=warning
 
-      - if: needs.changes.outputs.scripts == 'true'
+      - if: always()
         name: Lint cleanup-trap hygiene (RFC #2873)
         run: bash tests/e2e/lint_cleanup_traps.sh
 
-      - if: needs.changes.outputs.scripts == 'true'
+      - if: always()
         name: Run E2E bash unit tests (no live infra)
         run: |
           bash tests/e2e/test_model_slug.sh
 
-      - if: needs.changes.outputs.scripts == 'true'
+      - if: always()
         name: Test ECR promote-tenant-image script (mock-driven, no live infra)
         # Covers scripts/promote-tenant-image.sh — the codified
         # :staging-latest → :latest ECR promote + tenant fleet redeploy
@@ -387,7 +386,7 @@ jobs:
         run: |
           bash scripts/test-promote-tenant-image.sh
 
-      - if: needs.changes.outputs.scripts == 'true'
+      - if: always()
         name: Shellcheck promote-tenant-image script
         # scripts/ is excluded from the bulk shellcheck pass above (legacy
         # SC3040/SC3043 cleanup pending). Run shellcheck explicitly on
@@ -407,8 +406,8 @@ jobs:
     # ci_job_names() detects this as github.ref-gated and skips it from F1.
     # The step-level exit 0 handles the "not main push" case; the job-level
     # `if:` makes the gating explicit so the drift script sees it.
-    # continue-on-error removed (was mc#774 mask): step exits 0 when not applicable.
-    if: ${{ github.ref == 'refs/heads/staging' }}
+    # Runs on both main and staging pushes; step exits 0 when not applicable.
+    if: ${{ github.ref == 'refs/heads/main' || github.ref == 'refs/heads/staging' }}
     needs: [changes, canvas-build]
     steps:
       - name: Write deploy reminder to step summary
@@ -459,7 +458,6 @@ jobs:
   # Python Lint & Test — required check, always runs.
   python-lint:
     name: Python Lint & Test
-    needs: changes
     runs-on: ubuntu-latest
     # Phase 4 (RFC #219 §1): confirmed green on main 2026-05-12.
     continue-on-error: false
@@ -469,25 +467,25 @@ jobs:
       run:
         working-directory: workspace
     steps:
-      - if: needs.changes.outputs.python != 'true'
+      - if: false
         working-directory: .
         run: echo "No workspace/** changes — skipping real lint+test; this job always runs to satisfy the required-check name on branch protection."
-      - if: needs.changes.outputs.python == 'true'
+      - if: always()
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
-      - if: needs.changes.outputs.python == 'true'
+      - if: always()
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
         with:
           python-version: '3.11'
           cache: pip
           cache-dependency-path: workspace/requirements.txt
-      - if: needs.changes.outputs.python == 'true'
+      - if: always()
         run: pip install -r requirements.txt pytest pytest-asyncio pytest-cov sqlalchemy>=2.0.0
       # Coverage flags + fail-under floor moved into workspace/pytest.ini
       # (issue #1817) so local `pytest` and CI use identical config.
-      - if: needs.changes.outputs.python == 'true'
+      - if: always()
         run: python -m pytest --tb=short
 
-      - if: needs.changes.outputs.python == 'true'
+      - if: always()
         name: Per-file critical-path coverage (MCP / inbox / auth)
         # MCP-critical Python files have a per-file floor on top of the
         # 86% total floor in pytest.ini. See issue #2790 for full rationale.
@@ -552,86 +550,104 @@ jobs:
     # red silently merged through. See internal#286 for the three concrete
     # tonight-of-2026-05-11 incidents that prompted the emergency bump.
     #
-    # Three properties of this job each close a failure mode:
+    # This job deliberately has no `needs:`. Gitea 1.22/act_runner can mark a
+    # job-level `if: always()` + `needs:` sentinel as skipped before upstream
+    # jobs settle, leaving branch protection with a permanent pending
+    # `CI / all-required` context. Instead, this independent sentinel polls the
+    # required commit-status contexts for this SHA and fails if any fail, skip,
+    # or never emit.
     #
-    #  1. `if: always()` — runs even when an upstream fails. Without it the
-    #     sentinel is `skipped` and protection treats that as missing → merge
-    #     ungated.
+    # canvas-deploy-reminder is intentionally NOT included in all-required.needs.
+    # It is an informational main-push reminder, not a PR quality gate. Keeping
+    # it in this dependency list lets a skipped reminder skip the required
+    # sentinel before the `always()` guard can emit a branch-protection status.
     #
-    #  2. Assertion is `result == "success"` per dep, NOT `!= "failure"`.
-    #     A `skipped` upstream (job gated by `if:` evaluating false, matrix
-    #     entry that couldn't run) must NOT silently pass through.
-    #     `skipped`-as-green is exactly the failure mode this gate closes.
-    #
-    #  3. `needs:` is the canonical list of "what counts as required."
-    #     status_check_contexts will reference only `ci/all-required` (Step 5
-    #     follow-up — branch-protection PATCH is Owners-tier per
-    #     `feedback_never_admin_merge_bypass`, separate PR); a new job is
-    #     added simply by listing it in `needs:` here.
-    #     `.gitea/workflows/ci-required-drift.yml` files a [ci-drift] issue
-    #     hourly if this list diverges from status_check_contexts or from
-    #     audit-force-merge.yml's REQUIRED_CHECKS env (RFC §4 + §6).
-    #
-    # canvas-deploy-reminder is intentionally excluded from all-required.needs:
-    # it needs canvas-build, which is skipped on CI-only PRs (canvas=false).
-    # Including it in all-required.needs causes all-required to hang on
-    # every CI-only PR. Keep it runnable on PRs via its own
-    # `needs: [changes, canvas-build]` — the sentinel only aggregates the result.
-    #
-    # Phase 3 (RFC #219 §1) safety: underlying build jobs carry
-    # continue-on-error: true so their failures are masked to null (2026-05-12: re-enabled mc#774 interim)
-    # (Gitea suppresses status reporting for CoE jobs). This sentinel
-    # runs with continue-on-error: false so it always reports its
-    # result to the API — without this, the required-status entry
-    # (CI / all-required (pull_request)) is never created, which
-    # blocks PR merges. When Phase 3 ends, flip underlying jobs to
-    # continue-on-error: false; this sentinel can then be flipped to
-    # continue-on-error: true if a Phase-4 regression requires it.
     continue-on-error: false
     runs-on: ubuntu-latest
-    timeout-minutes: 1
-    needs:
-      - changes
-      - platform-build
-      - canvas-build
-      - shellcheck
-      - python-lint
-      - canvas-deploy-reminder
-    if: ${{ always() }}
+    timeout-minutes: 45
     steps:
-      - name: Assert every required dependency succeeded
+      - name: Wait for required CI contexts
+        env:
+          GITEA_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          API_ROOT: ${{ github.server_url }}/api/v1
+          REPOSITORY: ${{ github.repository }}
+          COMMIT_SHA: ${{ github.sha }}
+          EVENT_NAME: ${{ github.event_name }}
         run: |
           set -euo pipefail
-          # `needs.*.result` is one of: success | failure | cancelled | skipped | null.
-          # We assert success per dep (not != failure) — see RFC §2 reasoning above.
-          # Null results are skipped: they come from Phase 3 (continue-on-error: true
-          # suppresses status) or from jobs still in-flight. The sentinel succeeds
-          # rather than blocking PRs on Phase 3 noise.
-          results='${{ toJSON(needs) }}'
-          echo "$results"
-          echo "$results" | python3 -c '
-          import json, sys
-          ns = json.load(sys.stdin)
-          # Phase 3 masked: jobs with continue-on-error: true may report "failure"
-          # Remove when mc#774 handler test failures are resolved.
-          PHASE3_MASKED = {"platform-build"}
-          # Exclude null (Phase 3 suppressed / in-flight) from the bad list.
-          bad = [(k, v.get("result")) for k, v in ns.items()
-                 if v.get("result") not in ("success", None, "cancelled", "skipped") and k not in PHASE3_MASKED]
-          if bad:
-              print(f"FAIL: jobs not green:", file=sys.stderr)
-              for k, r in bad:
-                  print(f"  - {k}: {r}", file=sys.stderr)
-              sys.exit(1)
-          pending = [(k, v.get("result")) for k, v in ns.items()
-                     if v.get("result") is None]
-          cancelled = [(k, v.get("result")) for k, v in ns.items()
-                       if v.get("result") == "cancelled"]
-          if pending:
-              print(f"WARN: {len(pending)} job(s) still in-flight (result=null): " +
-                    ", ".join(k for k, _ in pending), file=sys.stderr)
-          if cancelled:
-              print(f"INFO: {len(cancelled)} job(s) masked by continue-on-error: " +
-                    ", ".join(k for k, _ in cancelled), file=sys.stderr)
-          print(f"OK: all {len(ns)} required jobs succeeded (or Phase-3 suppressed)")
-          '
+          python3 - <<'PY'
+          import json
+          import os
+          import sys
+          import time
+          import urllib.error
+          import urllib.request
+
+          token = os.environ["GITEA_TOKEN"]
+          api_root = os.environ["API_ROOT"].rstrip("/")
+          repo = os.environ["REPOSITORY"]
+          sha = os.environ["COMMIT_SHA"]
+          event = os.environ["EVENT_NAME"]
+          required = [
+              f"CI / Detect changes ({event})",
+              f"CI / Platform (Go) ({event})",
+              f"CI / Canvas (Next.js) ({event})",
+              f"CI / Shellcheck (E2E scripts) ({event})",
+              f"CI / Python Lint & Test ({event})",
+          ]
+          terminal_bad = {"failure", "error"}
+          deadline = time.time() + 40 * 60
+          last_summary = None
+
+          def fetch_statuses():
+              statuses = []
+              for page in range(1, 6):
+                  url = f"{api_root}/repos/{repo}/commits/{sha}/statuses?page={page}&limit=100"
+                  req = urllib.request.Request(url, headers={"Authorization": f"token {token}"})
+                  with urllib.request.urlopen(req, timeout=10) as resp:
+                      chunk = json.load(resp)
+                  if not chunk:
+                      break
+                  statuses.extend(chunk)
+              latest = {}
+              for item in statuses:
+                  ctx = item.get("context")
+                  if not ctx:
+                      continue
+                  prev = latest.get(ctx)
+                  if prev is None or (item.get("updated_at") or item.get("created_at") or "") >= (prev.get("updated_at") or prev.get("created_at") or ""):
+                      latest[ctx] = item
+              return latest
+
+          while True:
+              try:
+                  latest = fetch_statuses()
+              except (TimeoutError, OSError, urllib.error.URLError) as exc:
+                  if time.time() >= deadline:
+                      print(f"FAIL: status polling did not recover before deadline: {exc}", file=sys.stderr)
+                      sys.exit(1)
+                  print(f"WARN: status poll failed, retrying: {exc}", flush=True)
+                  time.sleep(15)
+                  continue
+              states = {ctx: (latest.get(ctx) or {}).get("status") or (latest.get(ctx) or {}).get("state") or "missing" for ctx in required}
+              summary = ", ".join(f"{ctx}={state}" for ctx, state in states.items())
+              if summary != last_summary:
+                  print(summary, flush=True)
+                  last_summary = summary
+              bad = {ctx: state for ctx, state in states.items() if state in terminal_bad}
+              if bad:
+                  print("FAIL: required CI context failed:", file=sys.stderr)
+                  for ctx, state in bad.items():
+                      desc = (latest.get(ctx) or {}).get("description") or ""
+                      print(f"  - {ctx}: {state} {desc}", file=sys.stderr)
+                  sys.exit(1)
+              if all(state == "success" for state in states.values()):
+                  print(f"OK: all {len(required)} required CI contexts succeeded")
+                  sys.exit(0)
+              if time.time() >= deadline:
+                  print("FAIL: timed out waiting for required CI contexts:", file=sys.stderr)
+                  for ctx, state in states.items():
+                      print(f"  - {ctx}: {state}", file=sys.stderr)
+                  sys.exit(1)
+              time.sleep(15)
+          PY

.gitea/workflows/e2e-api.yml

@@ -69,6 +69,13 @@ name: E2E API Smoke Test
 # 2318) shows Postgres ready in 3s, Redis in 1s, Platform in 1s when
 # they DO come up. Timeouts are not the bottleneck; not bumped.
 #
+# Item #1046 (fixed 2026-05-14): Stale platform-server from cancelled runs
+#   lingers on :8080 after "Stop platform" step is skipped (workflow cancelled
+#   before reaching line 335). Added a pre-start "Kill stale platform-server"
+#   step (line 286) that scans /proc for zombie platform-server processes
+#   and kills them before the port probe or bind. Makes the ephemeral port
+#   probe + start sequence deterministic.
+#
 # Item explicitly NOT fixed here: failing test `Status back online`
 # fails because the platform's langgraph workspace template image
 # (ghcr.io/molecule-ai/workspace-template-langgraph:latest) returns
@@ -283,6 +290,35 @@ jobs:
           echo "PORT=${PLATFORM_PORT}" >> "$GITHUB_ENV"
           echo "BASE=http://127.0.0.1:${PLATFORM_PORT}" >> "$GITHUB_ENV"
           echo "Platform host port: ${PLATFORM_PORT}"
+      - name: Kill stale platform-server before start (issue #1046)
+        if: needs.detect-changes.outputs.api == 'true'
+        run: |
+          # Concurrent runs on the same host-network act_runner can leave a
+          # zombie platform-server from a cancelled/timeout run. Cancelled
+          # runs never reach the "Stop platform" step (line 335), so the
+          # old process lingers. Kill it before the ephemeral port probe
+          # or start so the port is definitively free.
+          #
+          # /proc scan — works on any Linux without pkill/lsof/ss.
+          # comm field is truncated to 15 chars: "platform-serve" matches
+          # "platform-server". Verify with cmdline to avoid false positives.
+          killed=0
+          for pid in $(grep -l "platform-serve" /proc/[0-9]*/comm 2>/dev/null); do
+            kpid="${pid%/comm}"
+            kpid="${kpid##*/}"
+            cmdline=$(cat "/proc/${kpid}/cmdline" 2>/dev/null | tr '\0' ' ')
+            if echo "$cmdline" | grep -q "platform-server"; then
+              echo "Killing stale platform-server pid ${kpid}: ${cmdline}"
+              kill "$kpid" 2>/dev/null || true
+              killed=$((killed + 1))
+            fi
+          done
+          if [ "$killed" -gt 0 ]; then
+            sleep 2
+            echo "Killed $killed stale process(es); port(s) released."
+          else
+            echo "No stale platform-server found."
+          fi
       - name: Start platform (background)
         if: needs.detect-changes.outputs.api == 'true'
         working-directory: workspace-server
@@ -346,3 +382,4 @@ jobs:
         run: |
           docker rm -f "$PG_CONTAINER" 2>/dev/null || true
           docker rm -f "$REDIS_CONTAINER" 2>/dev/null || true
+

.gitea/workflows/e2e-chat.yml

@@ -97,7 +97,7 @@ jobs:
           cache-dependency-path: workspace-server/go.sum
 
       - if: needs.detect-changes.outputs.chat == 'true'
-        uses: actions/setup-node@60edb5dd545a775178f52524783378180af0d6f5 # v4
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
         with:
           node-version: '22'
           cache: 'npm'
@@ -175,6 +175,19 @@ jobs:
           echo "E2E_PLATFORM_URL=http://127.0.0.1:${PLATFORM_PORT}" >> "$GITHUB_ENV"
           echo "Platform host port: ${PLATFORM_PORT}"
 
+      - name: Pick canvas port
+        if: needs.detect-changes.outputs.chat == 'true'
+        run: |
+          CANVAS_PORT=$(python3 - <<'PY'
+          import socket
+          with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+              s.bind(("127.0.0.1", 0))
+              print(s.getsockname()[1])
+          PY
+          )
+          echo "CANVAS_PORT=${CANVAS_PORT}" >> "$GITHUB_ENV"
+          echo "Canvas host port: ${CANVAS_PORT}"
+
       - name: Start platform (background)
         if: needs.detect-changes.outputs.chat == 'true'
         working-directory: workspace-server
@@ -183,6 +196,7 @@ jobs:
           export DATABASE_URL="${DATABASE_URL}"
           export REDIS_URL="${REDIS_URL}"
           export PORT="${PLATFORM_PORT}"
+          export CORS_ORIGINS="http://localhost:3000,http://localhost:3001,http://localhost:${CANVAS_PORT},http://127.0.0.1:${CANVAS_PORT}"
           ./platform-server > platform.log 2>&1 &
           echo $! > platform.pid
 
@@ -216,10 +230,10 @@ jobs:
         run: |
           export NEXT_PUBLIC_PLATFORM_URL="http://127.0.0.1:${PLATFORM_PORT}"
           export NEXT_PUBLIC_WS_URL="ws://127.0.0.1:${PLATFORM_PORT}/ws"
-          npm run dev > canvas.log 2>&1 &
+          npx next dev --turbopack -p "${CANVAS_PORT}" > canvas.log 2>&1 &
           echo $! > canvas.pid
           for i in $(seq 1 30); do
-            if curl -sf http://localhost:3000 > /dev/null 2>&1; then
+            if curl -sf "http://localhost:${CANVAS_PORT}" > /dev/null 2>&1; then
               echo "Canvas up after ${i}s"
               exit 0
             fi
@@ -235,6 +249,7 @@ jobs:
         run: |
           export E2E_PLATFORM_URL="http://127.0.0.1:${PLATFORM_PORT}"
           export E2E_DATABASE_URL="${DATABASE_URL}"
+          export PLAYWRIGHT_BASE_URL="http://localhost:${CANVAS_PORT}"
           npx playwright test e2e/chat-desktop.spec.ts e2e/chat-mobile.spec.ts
 
       - name: Dump platform log on failure

.gitea/workflows/e2e-peer-visibility.yml

@@ -0,0 +1,225 @@
+name: E2E Peer Visibility (literal MCP list_peers)
+
+# WHY A DEDICATED WORKFLOW (not folded into e2e-staging-saas.yml)
+# --------------------------------------------------------------
+# This is the systemic fix for a real trust failure. Hermes and OpenClaw
+# were reported "fleet-verified / cascade-complete" because the *proxy*
+# signals were green (registry registration + heartbeat for Hermes; model
+# round-trip 200 for OpenClaw). A freshly-provisioned workspace asked on
+# canvas "can you see your peers" actually FAILS:
+#   - Hermes: 401 on the molecule MCP `list_peers` call
+#   - OpenClaw: native `sessions_list` fallback, sees no platform peers
+# Tasks #142/#159 were even marked "completed" under this proxy flaw.
+#
+# A dedicated workflow (vs extending e2e-staging-saas.yml) because:
+#   - It must provision MULTIPLE distinct runtimes (hermes, openclaw,
+#     claude-code) in ONE org and assert each sees the others. The
+#     full-saas script is single-runtime-per-run (E2E_RUNTIME) and folding
+#     a multi-runtime matrix into it would conflate concerns and bloat its
+#     already-45-min run.
+#   - It needs its own concurrency group so it doesn't fight full-saas /
+#     canvas for the staging org-creation quota.
+#   - It needs an independent, non-required status-context name so it can
+#     be RED today (the in-flight Hermes-401 / OpenClaw-MCP-wiring fixes
+#     have not landed) WITHOUT wedging unrelated merges — and flipped to
+#     REQUIRED in one branch-protection edit once it goes green
+#     (flip-to-required checklist: molecule-core#1296).
+#
+# THE ASSERTION IS NOT A PROXY. The driving script
+# tests/e2e/test_peer_visibility_mcp_staging.sh issues the byte-for-byte
+# JSON-RPC `tools/call name=list_peers` envelope to `POST
+# /workspaces/:id/mcp` using each workspace's OWN bearer token, through
+# the real WorkspaceAuth + MCPRateLimiter middleware chain — the exact
+# call mcp_molecule_list_peers makes from a canvas agent. It does NOT
+# read a registry row, /health, the heartbeat table, or
+# GET /registry/:id/peers.
+#
+# HONEST GATE — NO continue-on-error. Per feedback_fix_root_not_symptom a
+# fake-green mask would defeat the entire purpose. This workflow goes red
+# on today's broken behavior and green only when the root-cause fixes
+# actually land. It is intentionally NOT in branch_protections — see PR
+# body for the required-vs-not decision + flip tracking issue.
+#
+# Gitea 1.22.6 / act_runner notes honored:
+#   - No cross-repo `uses:` (feedback_gitea_cross_repo_uses_blocked). The
+#     actions/checkout SHA is the one e2e-staging-canvas.yml already uses
+#     successfully (a mirrored SHA — see #1277/PR#1292 root-cause).
+#   - Per-SHA concurrency, not global (feedback_concurrency_group_per_sha).
+#   - Workflow-level GITHUB_SERVER_URL pinned
+#     (feedback_act_runner_github_server_url).
+#   - pr-validate posts a status under the same check name so a
+#     workflow-only PR is not silently statusless and the context is
+#     flip-to-required-ready (mirrors e2e-staging-saas.yml's proven shape;
+#     real EC2-provisioning E2E is push/dispatch/cron only — it is 30+ min
+#     and cannot run per-PR-update).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'workspace-server/internal/handlers/mcp.go'
+      - 'workspace-server/internal/handlers/mcp_tools.go'
+      - 'workspace-server/internal/middleware/**'
+      - 'workspace-server/internal/handlers/registry.go'
+      - 'workspace-server/internal/handlers/workspace.go'
+      - 'workspace/a2a_mcp_server.py'
+      - 'workspace/platform_tools/registry.py'
+      - 'tests/e2e/test_peer_visibility_mcp_staging.sh'
+      - '.gitea/workflows/e2e-peer-visibility.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'workspace-server/internal/handlers/mcp.go'
+      - 'workspace-server/internal/handlers/mcp_tools.go'
+      - 'workspace-server/internal/middleware/**'
+      - 'workspace-server/internal/handlers/registry.go'
+      - 'workspace-server/internal/handlers/workspace.go'
+      - 'workspace/a2a_mcp_server.py'
+      - 'workspace/platform_tools/registry.py'
+      - 'tests/e2e/test_peer_visibility_mcp_staging.sh'
+      - '.gitea/workflows/e2e-peer-visibility.yml'
+  workflow_dispatch:
+  schedule:
+    # 07:30 UTC daily — catches AMI / template-hermes / template-openclaw
+    # drift even on quiet days. Offset 30m from e2e-staging-saas (07:00)
+    # so the two don't collide on the staging org-creation quota.
+    - cron: '30 7 * * *'
+
+concurrency:
+  # Per-SHA (feedback_concurrency_group_per_sha). A single global group
+  # would let a queued staging/main push behind a PR run get cancelled,
+  # leaving any gate that reads "completed run at SHA" stuck.
+  group: e2e-peer-visibility-${{ github.event.pull_request.head.sha || github.sha }}
+  cancel-in-progress: false
+
+env:
+  GITHUB_SERVER_URL: https://git.moleculesai.app
+
+jobs:
+  # PR path: post a real status under the required-ready check name so a
+  # workflow-only PR is never silently statusless. The actual EC2 E2E is
+  # push/dispatch/cron only (30+ min). This is NOT a fake-green mask of
+  # the real assertion — it validates the driving script's bash syntax
+  # and inline-python so a broken test script fails at PR time.
+  pr-validate:
+    name: E2E Peer Visibility
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Validate driving script
+        run: |
+          bash -n tests/e2e/test_peer_visibility_mcp_staging.sh
+          echo "test_peer_visibility_mcp_staging.sh — bash syntax OK"
+          echo "Real fresh-provision MCP list_peers E2E runs on push to"
+          echo "main / workflow_dispatch / daily cron (30+ min EC2 boot)."
+
+  # Real gate: provisions a throwaway org + sibling-per-runtime, drives
+  # the LITERAL list_peers MCP call per runtime, asserts 200 + expected
+  # peer set, then scoped teardown. push(main)/dispatch/cron only.
+  peer-visibility:
+    name: E2E Peer Visibility
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request'
+    timeout-minutes: 60
+
+    env:
+      MOLECULE_CP_URL: https://staging-api.moleculesai.app
+      MOLECULE_ADMIN_TOKEN: ${{ secrets.CP_STAGING_ADMIN_API_TOKEN }}
+      # LLM provider key so each runtime can authenticate at boot.
+      # Priority MiniMax → direct-Anthropic → OpenAI matches
+      # test_staging_full_saas.sh's secrets-injection chain.
+      E2E_MINIMAX_API_KEY: ${{ secrets.MOLECULE_STAGING_MINIMAX_API_KEY }}
+      E2E_ANTHROPIC_API_KEY: ${{ secrets.MOLECULE_STAGING_ANTHROPIC_API_KEY }}
+      E2E_OPENAI_API_KEY: ${{ secrets.MOLECULE_STAGING_OPENAI_API_KEY }}
+      E2E_RUN_ID: "${{ github.run_id }}-${{ github.run_attempt }}"
+      PV_RUNTIMES: "hermes openclaw claude-code"
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Verify admin token present
+        run: |
+          if [ -z "$MOLECULE_ADMIN_TOKEN" ]; then
+            echo "::error::CP_STAGING_ADMIN_API_TOKEN secret not set (Railway staging CP_ADMIN_API_TOKEN)"
+            exit 2
+          fi
+          echo "Admin token present"
+
+      - name: Verify an LLM key present
+        run: |
+          if [ -z "${E2E_MINIMAX_API_KEY:-}" ] && [ -z "${E2E_ANTHROPIC_API_KEY:-}" ] && [ -z "${E2E_OPENAI_API_KEY:-}" ]; then
+            echo "::error::No LLM provider key set — workspaces fail at boot with 'No provider API key found'. Set MOLECULE_STAGING_MINIMAX_API_KEY (or ANTHROPIC / OPENAI)."
+            exit 2
+          fi
+          echo "LLM key present"
+
+      - name: CP staging health preflight
+        run: |
+          code=$(curl -sS -o /dev/null -w "%{http_code}" --max-time 10 "$MOLECULE_CP_URL/health")
+          if [ "$code" != "200" ]; then
+            echo "::error::Staging CP unhealthy (HTTP $code) — infra, not a workspace bug. Failing loud per feedback_fix_root_not_symptom."
+            exit 1
+          fi
+          echo "Staging CP healthy"
+
+      - name: Run fresh-provision peer-visibility E2E (literal MCP list_peers)
+        run: bash tests/e2e/test_peer_visibility_mcp_staging.sh
+
+      # Belt-and-braces scoped teardown: the script installs an EXIT/INT/
+      # TERM trap, but if the runner itself is cancelled the trap may not
+      # fire. This always() step deletes ONLY the e2e-pv-<run_id> org this
+      # run created — never a cluster-wide sweep
+      # (feedback_never_run_cluster_cleanup_tests_on_live_platform). The
+      # admin DELETE is idempotent so double-invoking is safe;
+      # sweep-stale-e2e-orgs is the final net (slug starts with 'e2e-').
+      - name: Teardown safety net (runs on cancel/failure)
+        if: always()
+        env:
+          ADMIN_TOKEN: ${{ secrets.CP_STAGING_ADMIN_API_TOKEN }}
+        run: |
+          set +e
+          orgs=$(curl -sS "$MOLECULE_CP_URL/cp/admin/orgs?limit=500" \
+            -H "Authorization: Bearer $ADMIN_TOKEN" 2>/dev/null \
+            | python3 -c "
+          import json, sys, os, datetime
+          run_id = os.environ.get('GITHUB_RUN_ID', '')
+          try:
+              d = json.load(sys.stdin)
+          except Exception:
+              print(''); sys.exit(0)
+          # ONLY sweep slugs from THIS run. e2e-pv-<YYYYMMDD>-<run_id>-...
+          # Sweep today AND yesterday's UTC date so a midnight-crossing run
+          # still matches its own slug (same bug class as the saas/canvas
+          # safety nets).
+          today = datetime.date.today()
+          yest = today - datetime.timedelta(days=1)
+          dates = (today.strftime('%Y%m%d'), yest.strftime('%Y%m%d'))
+          if run_id:
+              prefixes = tuple(f'e2e-pv-{dt}-{run_id}-' for dt in dates)
+          else:
+              prefixes = tuple(f'e2e-pv-{dt}-' for dt in dates)
+          orgs = d if isinstance(d, list) else d.get('orgs', [])
+          cands = [o['slug'] for o in orgs
+                   if any(o.get('slug','').startswith(p) for p in prefixes)
+                   and o.get('instance_status') not in ('purged',)]
+          print('\n'.join(cands))
+          " 2>/dev/null)
+          for slug in $orgs; do
+            echo "Safety-net teardown: $slug"
+            set +e
+            curl -sS -o /tmp/pv-cleanup.out -w "%{http_code}" \
+              -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
+              -H "Authorization: Bearer $ADMIN_TOKEN" \
+              -H "Content-Type: application/json" \
+              -d "{\"confirm\":\"$slug\"}" >/tmp/pv-cleanup.code
+            set -e
+            code=$(cat /tmp/pv-cleanup.code 2>/dev/null || echo "000")
+            if [ "$code" = "200" ] || [ "$code" = "204" ]; then
+              echo "[teardown] deleted $slug (HTTP $code)"
+            else
+              echo "::warning::pv teardown for $slug returned HTTP $code — sweep-stale-e2e-orgs will catch it within MAX_AGE_MINUTES. Body: $(head -c 300 /tmp/pv-cleanup.out 2>/dev/null)"
+            fi
+          done
+          exit 0

.gitea/workflows/gate-check-v3.yml

@@ -83,25 +83,41 @@ jobs:
           REPO: ${{ github.repository }}
         run: |
           set -euo pipefail
-          # Fetch all open PRs and run gate-check on each
-          # socket.setdefaulttimeout(15): defence-in-depth for missing SOP_TIER_CHECK_TOKEN.
-          # gate_check.py uses timeout=15 on every urlopen call; this catches the
-          # inline Python polling loop too (issue #603).
+          # Fetch all open PRs and run gate-check on each. This scheduled
+          # refresher is advisory; a transient Gitea list timeout must not turn
+          # main red. PR-specific gate-check runs still use normal failure
+          # semantics.
           pr_numbers=$(python3 <<'PY'
           import json
           import os
           import socket
+          import sys
+          import time
+          import urllib.error
           import urllib.request
 
-          socket.setdefaulttimeout(15)
+          socket.setdefaulttimeout(30)
           token = os.environ["GITEA_TOKEN"]
           repo = os.environ["REPO"]
-          req = urllib.request.Request(
-              f"https://git.moleculesai.app/api/v1/repos/{repo}/pulls?state=open&limit=100",
-              headers={"Authorization": f"token {token}", "Accept": "application/json"},
-          )
-          with urllib.request.urlopen(req) as r:
-              prs = json.loads(r.read())
+          url = f"https://git.moleculesai.app/api/v1/repos/{repo}/pulls?state=open&limit=100"
+          last_error = None
+          for attempt in range(1, 4):
+              req = urllib.request.Request(
+                  url,
+                  headers={"Authorization": f"token {token}", "Accept": "application/json"},
+              )
+              try:
+                  with urllib.request.urlopen(req, timeout=30) as r:
+                      prs = json.loads(r.read())
+                  break
+              except (TimeoutError, OSError, urllib.error.URLError, urllib.error.HTTPError) as exc:
+                  last_error = exc
+                  print(f"warning: PR list fetch attempt {attempt}/3 failed: {exc}", file=sys.stderr)
+                  if attempt < 3:
+                      time.sleep(2 * attempt)
+          else:
+              print(f"warning: skipped scheduled gate-check refresh; failed to list open PRs after 3 attempts: {last_error}", file=sys.stderr)
+              raise SystemExit(0)
           for pr in prs:
               print(pr["number"])
           PY

.gitea/workflows/handlers-postgres-integration.yml

@@ -86,7 +86,11 @@ jobs:
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
-          fetch-depth: 0
+          # A full-history checkout can exceed the runner's quiet/startup
+          # window before the path filter emits logs. Fetch the common push
+          # case cheaply; the script below fetches the exact BASE SHA if it is
+          # not present in the shallow checkout.
+          fetch-depth: 2
       - id: filter
         # Inline replacement for dorny/paths-filter — see e2e-api.yml.
         run: |

.gitea/workflows/lint-continue-on-error-tracking.yml

@@ -93,7 +93,7 @@ jobs:
   lint:
     name: lint-continue-on-error-tracking
     runs-on: ubuntu-latest
-    timeout-minutes: 10
+    timeout-minutes: 20
     # Phase 3 (RFC #219 §1): surface masked defects without blocking
     # PRs. Pre-existing continue-on-error: true directives on main
     # all violate this lint at first — intentional. Flip to false

.gitea/workflows/review-refire-comments.yml

@@ -18,6 +18,10 @@ permissions:
   pull-requests: read
   statuses: write
 
+concurrency:
+  group: ${{ github.repository }}-${{ github.workflow }}-${{ github.event.issue.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   dispatch:
     runs-on: ubuntu-latest

.gitea/workflows/sop-checklist.yml

@@ -70,7 +70,7 @@ name: sop-checklist
 # Cancel any in-progress runs for the same PR to prevent
 # stale runs from overwriting newer status contexts.
 concurrency:
-  group: ${{ github.repository }}-${{ github.event.pull_request.number }}
+  group: ${{ github.repository }}-${{ github.workflow }}-${{ github.event.pull_request.number || github.event.issue.number || github.ref }}
   cancel-in-progress: true
 
 # bp-required: yes  ← emits sop-checklist / all-items-acked (pull_request)

.gitea/workflows/sop-tier-check.yml

@@ -61,6 +61,10 @@ on:
   pull_request_review:
     types: [submitted, dismissed, edited]
 
+concurrency:
+  group: ${{ github.repository }}-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
 jobs:
   tier-check:
     runs-on: ubuntu-latest

.staging-trigger

@@ -1 +1 @@
-staging trigger
+staging trigger 2026-05-14T17:35:02Z

_ci_trigger.txt

@@ -0,0 +1 @@
+trigger

canvas/playwright.config.ts

@@ -8,7 +8,7 @@ export default defineConfig({
   workers: 1,
   retries: 0,
   use: {
-    baseURL: "http://localhost:3000",
+    baseURL: process.env.PLAYWRIGHT_BASE_URL || "http://localhost:3000",
     headless: true,
     screenshot: "only-on-failure",
   },

canvas/src/app/orgs/page.tsx

@@ -212,7 +212,7 @@ function AccountBar({ session }: { session: Session }) {
           // edge cases (jsdom, blocked navigation) where it doesn't.
           setSigningOut(false);
         }}
-        className="rounded border border-line bg-surface-card px-3 py-1 text-xs text-ink hover:bg-surface-card disabled:opacity-50"
+        className="rounded border border-line bg-surface-card px-3 py-1 text-xs text-ink hover:bg-surface-card disabled:opacity-50 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-1"
         aria-label="Sign out"
       >
         {signingOut ? "Signing out…" : "Sign out"}

canvas/src/components/BroadcastBanner.tsx

@@ -0,0 +1,100 @@
+"use client";
+
+import { useCallback } from "react";
+import { useCanvasStore } from "@/store/canvas";
+
+/** Org-wide broadcast banner.
+ *
+ * Rendered at the top of the canvas (below the toolbar) whenever the store
+ * holds one or more unread BROADCAST_MESSAGE entries. Each entry shows:
+ *   - sender name (workspace that issued the broadcast)
+ *   - the message text
+ *   - a dismiss button
+ *
+ * Dismissing an entry removes it from the store via consumeBroadcastMessages.
+ * The dismissed state is intentionally ephemeral — dismissed broadcasts reappear
+ * on page refresh since they are not persisted server-side; this is intentional
+ * (the platform's activity log already provides the audit trail).
+ */
+export function BroadcastBanner() {
+  const broadcastMessages = useCanvasStore((s) => s.broadcastMessages);
+  const dismissBroadcastMessage = useCanvasStore((s) => s.dismissBroadcastMessage);
+
+  const handleDismiss = useCallback(
+    (id: string) => {
+      dismissBroadcastMessage(id);
+    },
+    [dismissBroadcastMessage],
+  );
+
+  if (broadcastMessages.length === 0) return null;
+
+  return (
+    <div className="fixed top-16 left-1/2 -translate-x-1/2 z-30 flex flex-col gap-2 items-center w-full max-w-xl px-4 pointer-events-none">
+      {broadcastMessages.map((msg) => (
+        <div
+          key={msg.id}
+          role="alert"
+          aria-live="polite"
+          aria-atomic="true"
+          className="pointer-events-auto w-full bg-blue-950/80 backdrop-blur-md border border-blue-700/50 rounded-xl px-5 py-3 shadow-2xl shadow-black/40 animate-in slide-in-from-top duration-300"
+        >
+          <div className="flex items-start gap-3">
+            {/* Megaphone icon */}
+            <div
+              aria-hidden="true"
+              className="w-7 h-7 rounded-lg bg-blue-900/50 flex items-center justify-center shrink-0 mt-0.5"
+            >
+              <svg
+                width="14"
+                height="14"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                className="text-blue-300"
+              >
+                <path d="M3 11l18-5v12L3 13v-2z" />
+                <path d="M11.6 16.8a3 3 0 1 1-5.8-1.6" />
+              </svg>
+            </div>
+
+            <div className="flex-1 min-w-0">
+              <div className="text-xs text-blue-300 font-semibold">
+                Broadcast from{" "}
+                <span className="text-blue-100">{msg.sender}</span>
+              </div>
+              <div className="text-sm text-blue-50 mt-0.5 leading-snug break-words">
+                {msg.message}
+              </div>
+            </div>
+
+            {/* Dismiss button */}
+            <button
+              type="button"
+              onClick={() => handleDismiss(msg.id)}
+              aria-label="Dismiss broadcast"
+              className="shrink-0 w-6 h-6 rounded text-blue-400 hover:text-blue-200 hover:bg-blue-800/50 flex items-center justify-center transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-blue-400 focus-visible:ring-offset-1 focus-visible:ring-offset-blue-950"
+            >
+              <svg
+                width="12"
+                height="12"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2.5"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+                aria-hidden="true"
+              >
+                <path d="M18 6 6 18M6 6l12 12" />
+              </svg>
+            </button>
+          </div>
+        </div>
+      ))}
+    </div>
+  );
+}

canvas/src/components/Canvas.tsx

@@ -21,6 +21,7 @@ import { CreateWorkspaceButton } from "./CreateWorkspaceDialog";
 import { ContextMenu } from "./ContextMenu";
 import { TemplatePalette } from "./TemplatePalette";
 import { ApprovalBanner } from "./ApprovalBanner";
+import { BroadcastBanner } from "./BroadcastBanner";
 import { BundleDropZone } from "./BundleDropZone";
 import { EmptyState } from "./EmptyState";
 import { OnboardingWizard } from "./OnboardingWizard";
@@ -367,6 +368,7 @@ function CanvasInner() {
         <OnboardingWizard />
         <Toolbar />
         <ApprovalBanner />
+        <BroadcastBanner />
         <BundleDropZone />
         <TemplatePalette />
         <SidePanel />

canvas/src/components/MissingKeysModal.tsx

@@ -471,7 +471,7 @@ function ProviderPickerModal({
             {onOpenSettings && (
               <button
                 onClick={onOpenSettings}
-                className="text-[11px] text-accent hover:text-accent transition-colors"
+                className="text-[11px] text-accent hover:text-accent transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
               >
                 Open Settings Panel
               </button>
@@ -480,7 +480,7 @@ function ProviderPickerModal({
           <div className="flex items-center gap-2">
             <button
               onClick={onCancel}
-              className="px-3.5 py-1.5 text-[12px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-card border border-line rounded-lg transition-colors"
+              className="px-3.5 py-1.5 text-[12px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-card border border-line rounded-lg transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
             >
               Cancel Deploy
             </button>

canvas/src/components/__tests__/BroadcastBanner.test.tsx

@@ -0,0 +1,111 @@
+// @vitest-environment jsdom
+/**
+ * Tests for BroadcastBanner component.
+ * WCAG compliance: role=alert, aria-live=polite, per-message dismiss.
+ */
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+import { BroadcastBanner } from "../BroadcastBanner";
+import { useCanvasStore } from "@/store/canvas";
+
+const mockDismiss = vi.fn();
+
+vi.mock("@/store/canvas", () => ({
+  useCanvasStore: vi.fn((selector: (s: ReturnType<typeof useCanvasStore.getState>) => unknown) => {
+    const state = {
+      broadcastMessages: [] as Array<{
+        id: string;
+        senderId: string;
+        sender: string;
+        message: string;
+        timestamp: string;
+      }>,
+      dismissBroadcastMessage: mockDismiss,
+    };
+    return selector(state);
+  }),
+}));
+
+afterEach(() => {
+  cleanup();
+  mockDismiss.mockClear();
+  vi.clearAllMocks();
+});
+
+const broadcastMessages = [
+  { id: "m1", senderId: "ws-ops", sender: "Ops Agent", message: "Deploy in 5 min", timestamp: "2026-05-16T00:00:00Z" },
+  { id: "m2", senderId: "ws-sre", sender: "SRE Team", message: "Maintenance window tonight", timestamp: "2026-05-16T00:01:00Z" },
+];
+
+function setup(messages = broadcastMessages) {
+  vi.mocked(useCanvasStore).mockImplementation(
+    (selector: (s: { broadcastMessages: typeof broadcastMessages; dismissBroadcastMessage: typeof mockDismiss }) => unknown) => {
+      const state = {
+        broadcastMessages: messages,
+        dismissBroadcastMessage: mockDismiss,
+      };
+      return selector(state);
+    }
+  );
+  return render(<BroadcastBanner />);
+}
+
+describe("BroadcastBanner", () => {
+  it("renders nothing when there are no messages", () => {
+    setup([]);
+    expect(screen.queryByRole("alert")).toBeNull();
+  });
+
+  it("renders a role=alert banner for each broadcast message", () => {
+    setup();
+    const alerts = screen.getAllByRole("alert");
+    expect(alerts).toHaveLength(2);
+  });
+
+  it("shows sender name and message content", () => {
+    setup();
+    expect(screen.getByText("Deploy in 5 min")).toBeTruthy();
+    expect(screen.getByText("Ops Agent")).toBeTruthy();
+    expect(screen.getByText("Maintenance window tonight")).toBeTruthy();
+    expect(screen.getByText("SRE Team")).toBeTruthy();
+  });
+
+  it("each banner has a dismiss button with accessible label", () => {
+    setup();
+    const buttons = screen.getAllByRole("button", { name: /dismiss/i });
+    expect(buttons).toHaveLength(2);
+  });
+
+  it("dismissing a banner calls dismissBroadcastMessage with the correct id", () => {
+    setup();
+    const buttons = screen.getAllByRole("button", { name: /dismiss/i });
+    // Dismiss the second message (Maintenance window)
+    fireEvent.click(buttons[1]);
+    expect(mockDismiss).toHaveBeenCalledTimes(1);
+    expect(mockDismiss).toHaveBeenCalledWith("m2");
+  });
+
+  it("dismissing one banner does not dismiss others", () => {
+    setup();
+    const buttons = screen.getAllByRole("button", { name: /dismiss/i });
+    fireEvent.click(buttons[0]);
+    expect(mockDismiss).toHaveBeenCalledWith("m1");
+    expect(mockDismiss).toHaveBeenCalledTimes(1);
+  });
+
+  it("dismiss button has focus-visible ring (WCAG 2.4.7)", () => {
+    setup();
+    const button = screen.getAllByRole("button", { name: /dismiss/i })[0];
+    expect(button.className).toContain("focus-visible:ring");
+  });
+
+  it("sender and message text use adequate contrast color classes", () => {
+    setup();
+    // text-blue-300 (#93C5FD) on blue-950/80 ≈ 5.9:1 contrast — WCAG AA ✓
+    const senderLabel = screen.getByText("Ops Agent").closest("div");
+    expect(senderLabel?.className).toContain("text-blue-300");
+    // text-blue-50 (#EFF6FF) on blue-950/80 ≈ 11.7:1 — WCAG AAA ✓
+    const messageEl = screen.getByText("Deploy in 5 min");
+    expect(messageEl.className).toContain("text-blue-50");
+  });
+});

canvas/src/components/__tests__/Canvas.a11y.test.tsx

@@ -73,6 +73,8 @@ const mockStoreState = {
   clearSelection: vi.fn(),
   toggleNodeSelection: vi.fn(),
   deletingIds: new Set<string>(),
+  broadcastMessages: [],
+  consumeBroadcastMessages: vi.fn(() => []),
 };
 
 vi.mock("@/store/canvas", () => ({
@@ -100,6 +102,7 @@ vi.mock("../ConfirmDialog", () => ({ ConfirmDialog: () => null }));
 vi.mock("../TemplatePalette", () => ({ TemplatePalette: () => null }));
 vi.mock("../OnboardingWizard", () => ({ OnboardingWizard: () => null }));
 vi.mock("../ApprovalBanner", () => ({ ApprovalBanner: () => null }));
+vi.mock("../BroadcastBanner", () => ({ BroadcastBanner: () => null }));
 vi.mock("../BundleDropZone", () => ({ BundleDropZone: () => null }));
 vi.mock("../CreateWorkspaceDialog", () => ({ CreateWorkspaceButton: () => null }));
 vi.mock("../settings", () => ({

canvas/src/components/__tests__/Canvas.pan-to-node.test.tsx

@@ -91,6 +91,8 @@ const mockStoreState = {
   // an empty Set mirrors the idle canvas and doesn't interact with
   // any pan/fit behaviour under test here.
   deletingIds: new Set<string>(),
+  broadcastMessages: [],
+  consumeBroadcastMessages: vi.fn(() => []),
 };
 
 vi.mock("@/store/canvas", () => ({
@@ -117,6 +119,7 @@ vi.mock("../ConfirmDialog", () => ({ ConfirmDialog: () => null }));
 vi.mock("../TemplatePalette", () => ({ TemplatePalette: () => null }));
 vi.mock("../OnboardingWizard", () => ({ OnboardingWizard: () => null }));
 vi.mock("../ApprovalBanner", () => ({ ApprovalBanner: () => null }));
+vi.mock("../BroadcastBanner", () => ({ BroadcastBanner: () => null }));
 vi.mock("../BundleDropZone", () => ({ BundleDropZone: () => null }));
 vi.mock("../CreateWorkspaceDialog", () => ({ CreateWorkspaceButton: () => null }));
 vi.mock("../settings", () => ({

canvas/src/components/canvas/__tests__/DropTargetBadge.test.tsx

@@ -195,6 +195,47 @@ describe("DropTargetBadge — renders ghost slot + badge for valid drag target",
     expect(screen.getByTestId("ghost-slot").style.height).toBe("260px");
   });
 
+  it("ghost has aria-hidden=true (decorative visual affordance)", () => {
+    _getInternalNode.mockReturnValue({
+      internals: { positionAbsolute: { x: 100, y: 200 } },
+      measured: { width: 220, height: 500 },
+    });
+    setFlowMock(({ x, y }: { x: number; y: number }) => {
+      if (x === 210 && y === 200) return { x: 420, y: 400 };
+      if (x === 116 && y === 330) return { x: 232, y: 660 };
+      if (x === 356 && y === 460) return { x: 712, y: 920 };
+      if (x === 100 && y === 200) return { x: 200, y: 400 };
+      if (x === 320 && y === 700) return { x: 640, y: 1400 };
+      return { x: x * 2, y: y * 2 };
+    });
+
+    setStore({
+      dragOverNodeId: "ws-target",
+      nodes: [
+        { id: "ws-target", data: { name: "Target" }, parentId: null, measured: { width: 220, height: 500 } },
+      ],
+    });
+    render(<DropTargetBadge />);
+    const ghost = screen.getByTestId("ghost-slot");
+    expect(ghost.getAttribute("aria-hidden")).toBe("true");
+  });
+
+  it("drop badge has role=status and aria-label including target name", () => {
+    _getInternalNode.mockReturnValue({
+      internals: { positionAbsolute: { x: 100, y: 200 } },
+      measured: { width: 220, height: 120 },
+    });
+    setFlowMock(({ x, y }: { x: number; y: number }) => ({ x: x * 2, y: y * 2 }));
+    setStore({
+      dragOverNodeId: "ws-target",
+      nodes: [{ id: "ws-target", data: { name: "Ops Workspace" }, parentId: null }],
+    });
+    render(<DropTargetBadge />);
+    const badge = screen.getByTestId("drop-badge");
+    expect(badge.getAttribute("role")).toBe("status");
+    expect(badge.getAttribute("aria-label")).toBe("Drop target: Ops Workspace");
+  });
+
   it("ghost is hidden when slot falls entirely outside parent bounds", () => {
     _getInternalNode.mockReturnValue({
       internals: { positionAbsolute: { x: 100, y: 200 } },

canvas/src/components/mobile/MobileCanvas.tsx

@@ -205,6 +205,7 @@ export function MobileCanvas({
           type="button"
           onClick={resetView}
           aria-label="Reset zoom"
+          className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
           style={{
             position: "absolute",
             right: 14,
@@ -272,6 +273,7 @@ export function MobileCanvas({
             key={l.agent.id}
             type="button"
             onClick={() => onOpen(l.agent.id)}
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               position: "absolute",
               left: `${l.x}%`,
@@ -376,6 +378,7 @@ export function MobileCanvas({
         type="button"
         onClick={onSpawn}
         aria-label="Spawn new agent"
+        className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
         style={{
           position: "absolute",
           right: 24,

canvas/src/components/mobile/MobileChat.tsx

@@ -6,21 +6,21 @@
 // attachments, no A2A topology overlay, no conversation tracing.
 
 import { useEffect, useMemo, useRef, useState } from "react";
-import ReactMarkdown from "react-markdown";
-import remarkGfm from "remark-gfm";
 
+import { api } from "@/lib/api";
 import { useCanvasStore } from "@/store/canvas";
-import { type ChatAttachment, type ChatMessage, createMessage } from "@/components/tabs/chat/types";
-import {
-  useChatHistory,
-  useChatSend,
-  useChatSocket,
-} from "@/components/tabs/chat/hooks";
 
 import { toMobileAgent } from "./components";
 import { MOBILE_FONT_MONO, MOBILE_FONT_SANS, usePalette } from "./palette";
 import { Icons, StatusDot, TierChip } from "./primitives";
 
+interface ChatMessage {
+  id: string;
+  role: "user" | "agent" | "system";
+  text: string;
+  ts: string;
+}
+
 const formatStoredTimestamp = (iso: string): string => {
   const d = new Date(iso);
   if (isNaN(d.getTime())) return "";
@@ -29,171 +29,29 @@ const formatStoredTimestamp = (iso: string): string => {
 
 type SubTab = "my" | "a2a";
 
-function MarkdownBubble({
-  children,
-  dark,
-  accent,
-}: {
-  children: string;
-  dark: boolean;
-  accent: string;
-}) {
-  const codeBg = dark ? "rgba(255,255,255,0.08)" : "rgba(0,0,0,0.06)";
-  const codeBlockBg = dark ? "#1a1a1a" : "#f5f5f0";
-  const linkColor = accent;
-  const quoteBorder = dark ? "rgba(255,250,240,0.15)" : "rgba(40,30,20,0.15)";
-
-  return (
-    <ReactMarkdown
-      remarkPlugins={[remarkGfm]}
-      components={{
-        p: ({ children }) => (
-          <div style={{ margin: "2px 0", lineHeight: "inherit" }}>{children}</div>
-        ),
-        a: ({ href, children }) => (
-          <a
-            href={href}
-            target="_blank"
-            rel="noopener noreferrer"
-            style={{ color: linkColor, textDecoration: "underline" }}
-          >
-            {children}
-          </a>
-        ),
-        pre: ({ children }) => (
-          <pre
-            style={{
-              background: codeBlockBg,
-              padding: "8px 10px",
-              borderRadius: 8,
-              overflow: "auto",
-              fontSize: 12,
-              lineHeight: 1.5,
-              fontFamily: MOBILE_FONT_MONO,
-              margin: "4px 0",
-            }}
-          >
-            {children}
-          </pre>
-        ),
-        code: ({ children, className }) => {
-          const isBlock = className != null && String(className).length > 0;
-          if (isBlock) {
-            return (
-              <code style={{ fontFamily: MOBILE_FONT_MONO, fontSize: 12 }}>
-                {children}
-              </code>
-            );
-          }
-          return (
-            <code
-              style={{
-                background: codeBg,
-                padding: "1px 4px",
-                borderRadius: 4,
-                fontSize: 13,
-                fontFamily: MOBILE_FONT_MONO,
-              }}
-            >
-              {children}
-            </code>
-          );
-        },
-        ul: ({ children }) => (
-          <ul style={{ margin: "4px 0", paddingLeft: 18, listStyle: "disc" }}>
-            {children}
-          </ul>
-        ),
-        ol: ({ children }) => (
-          <ol style={{ margin: "4px 0", paddingLeft: 18, listStyle: "decimal" }}>
-            {children}
-          </ol>
-        ),
-        li: ({ children }) => <li style={{ margin: "2px 0" }}>{children}</li>,
-        strong: ({ children }) => (
-          <strong style={{ fontWeight: 600 }}>{children}</strong>
-        ),
-        em: ({ children }) => <em style={{ fontStyle: "italic" }}>{children}</em>,
-        h1: ({ children }) => (
-          <div style={{ fontSize: 16, fontWeight: 700, margin: "4px 0" }}>{children}</div>
-        ),
-        h2: ({ children }) => (
-          <div style={{ fontSize: 15, fontWeight: 700, margin: "4px 0" }}>{children}</div>
-        ),
-        h3: ({ children }) => (
-          <div style={{ fontSize: 14, fontWeight: 700, margin: "4px 0" }}>{children}</div>
-        ),
-        h4: ({ children }) => (
-          <div style={{ fontSize: 14, fontWeight: 600, margin: "4px 0" }}>{children}</div>
-        ),
-        h5: ({ children }) => (
-          <div style={{ fontSize: 13, fontWeight: 600, margin: "4px 0" }}>{children}</div>
-        ),
-        h6: ({ children }) => (
-          <div style={{ fontSize: 13, fontWeight: 600, margin: "4px 0" }}>{children}</div>
-        ),
-        blockquote: ({ children }) => (
-          <blockquote
-            style={{
-              borderLeft: `2px solid ${quoteBorder}`,
-              margin: "4px 0",
-              paddingLeft: 8,
-              opacity: 0.85,
-            }}
-          >
-            {children}
-          </blockquote>
-        ),
-        hr: () => (
-          <hr
-            style={{
-              border: "none",
-              borderTop: `0.5px solid ${quoteBorder}`,
-              margin: "6px 0",
-            }}
-          />
-        ),
-        table: ({ children }) => (
-          <table
-            style={{
-              borderCollapse: "collapse",
-              fontSize: 13,
-              margin: "4px 0",
-              width: "100%",
-            }}
-          >
-            {children}
-          </table>
-        ),
-        thead: ({ children }) => <thead style={{ fontWeight: 600 }}>{children}</thead>,
-        th: ({ children }) => (
-          <th
-            style={{
-              border: `0.5px solid ${quoteBorder}`,
-              padding: "4px 6px",
-              textAlign: "left",
-            }}
-          >
-            {children}
-          </th>
-        ),
-        td: ({ children }) => (
-          <td
-            style={{
-              border: `0.5px solid ${quoteBorder}`,
-              padding: "4px 6px",
-            }}
-          >
-            {children}
-          </td>
-        ),
-      }}
-    >
-      {children}
-    </ReactMarkdown>
-  );
+interface A2AResponseShape {
+  result?: {
+    parts?: Array<{ kind?: string; text?: string }>;
+  };
+  error?: { message?: string };
 }
 
+// Wire shape for GET /workspaces/:id/chat-history (chat_history.go → ChatHistoryResponse).
+interface ApiChatMessage {
+  id: string;
+  role: string; // "user" | "agent" | "system"
+  content: string;
+  timestamp: string;
+}
+
+interface ChatHistoryResponse {
+  messages: ApiChatMessage[];
+  reached_end: boolean;
+}
+
+const formatTime = (date: Date) =>
+  date.toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
+
 export function MobileChat({
   agentId,
   dark,
@@ -204,40 +62,31 @@ export function MobileChat({
   onBack: () => void;
 }) {
   const p = usePalette(dark);
+  // Selecting `nodes` stably avoids the `.find()` anti-pattern that
+  // creates a new return value on every store update (React error #185).
   const nodes = useCanvasStore((s) => s.nodes);
   const node = useMemo(() => nodes.find((n) => n.id === agentId), [nodes, agentId]);
+  // Bootstrap from the canvas store's per-workspace message buffer so the
+  // user sees their prior thread on entry. The store is updated by the
+  // socket → ChatTab flows the desktop runs; on mobile we read from the
+  // same buffer to keep state coherent across viewports.
+  // NOTE: selector returns undefined (stable) — do NOT use ?? [] here,
+  // that creates a new [] reference on every store update when the key is
+  // absent, causing infinite re-render (React error #185).
+  const storedMessages = useCanvasStore((s) => s.agentMessages[agentId]);
+  // Start empty — history is loaded via useEffect below.
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
   const [draft, setDraft] = useState("");
   const [tab, setTab] = useState<SubTab>("my");
+  const [sending, setSending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [loading, setLoading] = useState(true); // history is loading on mount
+  const [historyError, setHistoryError] = useState<string | null>(null);
   const scrollRef = useRef<HTMLDivElement>(null);
+  // Guard: don't treat the initial store population as a live push.
+  // Set to false after the first render completes.
+  const initDoneRef = useRef(false);
   const composerRef = useRef<HTMLTextAreaElement>(null);
-  const fileInputRef = useRef<HTMLInputElement>(null);
-  const [pendingFiles, setPendingFiles] = useState<File[]>([]);
-
-  const {
-    messages,
-    loading: historyLoading,
-    loadError: historyError,
-    loadInitial,
-    appendMessageDeduped,
-  } = useChatHistory(agentId);
-
-  const {
-    sending,
-    uploading,
-    sendMessage,
-    error: sendError,
-    clearError,
-    releaseSendGuards,
-  } = useChatSend(agentId, {
-    getHistoryMessages: () => messages,
-    onUserMessage: appendMessageDeduped,
-    onAgentMessage: appendMessageDeduped,
-  });
-
-  useChatSocket(agentId, {
-    onAgentMessage: appendMessageDeduped,
-    onSendComplete: releaseSendGuards,
-  });
 
   // Auto-grow the textarea: reset height to 'auto' so the scrollHeight
   // shrinks when the user deletes text, then size to scrollHeight up to
@@ -250,26 +99,81 @@ export function MobileChat({
     el.style.height = `${next}px`;
   }, [draft]);
 
+  // Fetch chat history on mount; keep merging live agentMessages while the
+  // panel is open. InitDoneRef prevents the initial store snapshot from
+  // triggering the live-merge path (the store buffer is populated by
+  // ChatTab on desktop, not on mobile — this effect loads history as the
+  // mobile-native path).
+  useEffect(() => {
+    let cancelled = false;
+
+    const mapApiMessage = (m: ApiChatMessage): ChatMessage => ({
+      id: m.id,
+      role: m.role === "user" ? "user" : "agent",
+      text: m.content,
+      ts: formatStoredTimestamp(m.timestamp),
+    });
+
+    const syncLive = () => {
+      const live = useCanvasStore.getState().agentMessages[agentId] ?? [];
+      if (live.length > 0) {
+        setMessages((prev) => {
+          const existingIds = new Set(prev.map((m) => m.id));
+          const newOnes = live
+            .filter((m) => !existingIds.has(m.id))
+            .map((m) => ({
+              id: m.id,
+              role: "agent" as const,
+              text: m.content,
+              ts: formatStoredTimestamp(m.timestamp),
+            }));
+          return newOnes.length > 0 ? [...prev, ...newOnes] : prev;
+        });
+      }
+    };
+
+    const bootstrap = async (): Promise<(() => void) | undefined> => {
+      setLoading(true);
+      setHistoryError(null);
+      try {
+        const res = await api.get<ChatHistoryResponse>(
+          `/workspaces/${agentId}/chat-history?limit=50`,
+        );
+        if (cancelled) return;
+        const initial = (res.messages ?? []).map(mapApiMessage);
+        setMessages(initial);
+        // Mark init done BEFORE marking loading=false so any store push
+        // that arrives in the same tick is treated as live, not init.
+        initDoneRef.current = true;
+        setLoading(false);
+        // Subscribe to live pushes after init is complete.
+        syncLive();
+        const unsubscribe = useCanvasStore.subscribe(syncLive);
+        return unsubscribe; // returned for cleanup
+      } catch (e) {
+        if (cancelled) return;
+        setHistoryError(e instanceof Error ? e.message : "Failed to load chat history");
+        setLoading(false);
+        initDoneRef.current = true;
+        return undefined;
+      }
+    };
+
+    let maybeUnsubscribe: (() => void) | undefined;
+    bootstrap().then((fn) => { maybeUnsubscribe = fn; });
+
+    return () => {
+      cancelled = true;
+      if (maybeUnsubscribe) maybeUnsubscribe();
+    };
+  }, [agentId]);
+
   useEffect(() => {
     if (scrollRef.current) {
       scrollRef.current.scrollTop = scrollRef.current.scrollHeight;
     }
   }, [messages]);
 
-  // Consume any agent messages that arrived while history was loading.
-  const initialConsumeDoneRef = useRef(false);
-  useEffect(() => {
-    if (historyLoading || initialConsumeDoneRef.current) return;
-    initialConsumeDoneRef.current = true;
-    const consume = useCanvasStore.getState().consumeAgentMessages;
-    const msgs = consume(agentId);
-    for (const m of msgs) {
-      appendMessageDeduped(
-        createMessage("agent", m.content, m.attachments),
-      );
-    }
-  }, [historyLoading, agentId, appendMessageDeduped]);
-
   if (!node) {
     return (
       <div
@@ -291,27 +195,51 @@ export function MobileChat({
   const a = toMobileAgent(node);
   const reachable = a.status === "online" || a.status === "degraded";
 
-  const onFilesPicked = (fileList: FileList | null) => {
-    if (!fileList) return;
-    const picked = Array.from(fileList);
-    setPendingFiles((prev) => {
-      const keyed = new Set(prev.map((f) => `${f.name}:${f.size}`));
-      return [...prev, ...picked.filter((f) => !keyed.has(`${f.name}:${f.size}`))];
-    });
-    if (fileInputRef.current) fileInputRef.current.value = "";
-  };
-
-  const removePendingFile = (index: number) =>
-    setPendingFiles((prev) => prev.filter((_, i) => i !== index));
-
   const send = async () => {
     const text = draft.trim();
-    if ((!text && pendingFiles.length === 0) || sending || !reachable) return;
-    clearError();
+    if (!text || sending || !reachable) return;
     setDraft("");
-    const files = pendingFiles;
-    setPendingFiles([]);
-    await sendMessage(text, files);
+    setError(null);
+    setSending(true);
+    const myMsg: ChatMessage = {
+      id: crypto.randomUUID(),
+      role: "user",
+      text,
+      ts: formatTime(new Date()),
+    };
+    setMessages((m) => [...m, myMsg]);
+
+    try {
+      const res = await api.post<A2AResponseShape>(`/workspaces/${agentId}/a2a`, {
+        method: "message/send",
+        params: {
+          message: {
+            role: "user",
+            messageId: crypto.randomUUID(),
+            parts: [{ kind: "text", text }],
+          },
+        },
+      });
+      const reply =
+        res.result?.parts?.find((part) => part.kind === "text")?.text ?? "";
+      if (reply) {
+        setMessages((m) => [
+          ...m,
+          {
+            id: crypto.randomUUID(),
+            role: "agent",
+            text: reply,
+            ts: formatTime(new Date()),
+          },
+        ]);
+      } else if (res.error?.message) {
+        setError(res.error.message);
+      }
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Failed to send");
+    } finally {
+      setSending(false);
+    }
   };
 
   return (
@@ -339,6 +267,7 @@ export function MobileChat({
             type="button"
             onClick={onBack}
             aria-label="Back"
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               width: 36,
               height: 36,
@@ -385,6 +314,7 @@ export function MobileChat({
           <button
             type="button"
             aria-label="More"
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               width: 36,
               height: 36,
@@ -415,6 +345,7 @@ export function MobileChat({
                 key={t.id}
                 type="button"
                 onClick={() => setTab(t.id)}
+                className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
                 style={{
                   padding: "4px 0 8px",
                   border: "none",
@@ -457,12 +388,13 @@ export function MobileChat({
             Agent Comms — peer-to-peer A2A traffic surfaces in the Comms tab.
           </div>
         )}
-        {tab === "my" && historyLoading && (
+        {tab === "my" && loading && (
           <div style={{ padding: "20px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
-            Loading chat history…
+            <div style={{ marginBottom: 6, opacity: 0.6, animation: "spin 1s linear infinite", display: "inline-block", fontSize: 16 }}>⟳</div>
+            <div>Loading chat history…</div>
           </div>
         )}
-        {tab === "my" && !historyLoading && historyError && messages.length === 0 && (
+        {tab === "my" && !loading && historyError && (
           <div
             role="alert"
             style={{
@@ -475,9 +407,29 @@ export function MobileChat({
             <div style={{ marginBottom: 8 }}>Could not load chat history.</div>
             <button
               type="button"
+              aria-label="Retry loading chat history"
               onClick={() => {
-                loadInitial();
+                setLoading(true);
+                setHistoryError(null);
+                api.get(`/workspaces/${agentId}/chat-history?limit=50`).then(
+                  (res: unknown) => {
+                    const r = res as ChatHistoryResponse;
+                    setMessages((r.messages ?? []).map((m) => ({
+                      id: m.id,
+                      role: m.role === "user" ? "user" : "agent",
+                      text: m.content,
+                      ts: formatStoredTimestamp(m.timestamp),
+                    })));
+                    setLoading(false);
+                    initDoneRef.current = true;
+                  },
+                ).catch((e: unknown) => {
+                  setHistoryError(e instanceof Error ? e.message : "Failed to load");
+                  setLoading(false);
+                  initDoneRef.current = true;
+                });
               }}
+              className="focus:outline-none focus-visible:ring-2 focus-visible:ring-[var(--color-failed,#ef4444)] focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
               style={{
                 padding: "6px 14px",
                 borderRadius: 14,
@@ -492,7 +444,7 @@ export function MobileChat({
             </button>
           </div>
         )}
-        {tab === "my" && !historyLoading && !historyError && messages.length === 0 && (
+        {tab === "my" && !loading && !historyError && messages.length === 0 && (
           <div style={{ padding: "20px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
             Send a message to start chatting.
           </div>
@@ -521,9 +473,7 @@ export function MobileChat({
                     overflowWrap: "anywhere",
                   }}
                 >
-                  <MarkdownBubble dark={dark} accent={p.accent}>
-                    {m.content}
-                  </MarkdownBubble>
+                  {m.text}
                   <div
                     style={{
                       fontSize: 10,
@@ -532,13 +482,13 @@ export function MobileChat({
                       fontFamily: MOBILE_FONT_MONO,
                     }}
                   >
-                    {formatStoredTimestamp(m.timestamp)}
+                    {m.ts}
                   </div>
                 </div>
               </div>
             );
           })}
-        {sendError && (
+        {error && (
           <div
             role="alert"
             style={{
@@ -550,7 +500,7 @@ export function MobileChat({
               fontSize: 12,
             }}
           >
-            {sendError}
+            {error}
           </div>
         )}
       </div>
@@ -581,60 +531,6 @@ export function MobileChat({
           backdropFilter: "blur(14px)",
         }}
       >
-        {pendingFiles.length > 0 && (
-          <div
-            style={{
-              display: "flex",
-              flexWrap: "wrap",
-              gap: 6,
-              marginBottom: 8,
-              paddingLeft: 2,
-            }}
-          >
-            {pendingFiles.map((f, i) => (
-              <div
-                key={`${f.name}:${f.size}`}
-                style={{
-                  display: "flex",
-                  alignItems: "center",
-                  gap: 4,
-                  padding: "3px 8px",
-                  borderRadius: 10,
-                  background: dark ? "#2a2823" : "#ece9e0",
-                  fontSize: 12,
-                  color: p.text2,
-                  maxWidth: "100%",
-                }}
-              >
-                <span
-                  style={{
-                    overflow: "hidden",
-                    textOverflow: "ellipsis",
-                    whiteSpace: "nowrap",
-                  }}
-                >
-                  {f.name}
-                </span>
-                <button
-                  type="button"
-                  onClick={() => removePendingFile(i)}
-                  aria-label={`Remove ${f.name}`}
-                  style={{
-                    border: "none",
-                    background: "transparent",
-                    color: p.text3,
-                    cursor: "pointer",
-                    fontSize: 12,
-                    padding: 0,
-                    lineHeight: 1,
-                  }}
-                >
-                  ✕
-                </button>
-              </div>
-            ))}
-          </div>
-        )}
         <div
           style={{
             display: "flex",
@@ -646,32 +542,22 @@ export function MobileChat({
             padding: "6px 6px 6px 12px",
           }}
         >
-          <input
-            ref={fileInputRef}
-            type="file"
-            multiple
-            style={{ display: "none" }}
-            onChange={(e) => onFilesPicked(e.target.files)}
-            aria-hidden="true"
-          />
           <button
             type="button"
-            onClick={() => fileInputRef.current?.click()}
-            disabled={!reachable || sending || uploading}
             aria-label="Attach"
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               width: 32,
               height: 32,
               borderRadius: 999,
               border: "none",
-              cursor: reachable && !sending && !uploading ? "pointer" : "not-allowed",
+              cursor: "pointer",
               background: "transparent",
               color: p.text3,
               flexShrink: 0,
               display: "flex",
               alignItems: "center",
               justifyContent: "center",
-              opacity: !reachable || sending || uploading ? 0.4 : 1,
             }}
           >
             {Icons.attach({ size: 16 })}
@@ -698,6 +584,7 @@ export function MobileChat({
             placeholder={reachable ? "Send a message…" : `Agent is ${a.status}`}
             disabled={!reachable}
             rows={1}
+            className="focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1"
             style={{
               flex: 1,
               border: "none",
@@ -717,32 +604,29 @@ export function MobileChat({
           <button
             type="button"
             onClick={send}
-            disabled={(!draft.trim() && pendingFiles.length === 0) || !reachable || sending || uploading}
+            disabled={!draft.trim() || !reachable || sending}
             aria-label="Send"
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               width: 36,
               height: 36,
               borderRadius: 999,
               border: "none",
-              cursor: (draft.trim() || pendingFiles.length > 0) && !sending && !uploading ? "pointer" : "not-allowed",
+              cursor: draft.trim() && !sending ? "pointer" : "not-allowed",
               flexShrink: 0,
               background:
-                (draft.trim() || pendingFiles.length > 0) && reachable && !sending && !uploading
+                draft.trim() && reachable && !sending
                   ? p.accent
                   : dark
                     ? "#2a2823"
                     : "#ece9e0",
-              color: (draft.trim() || pendingFiles.length > 0) && reachable && !sending && !uploading ? "#fff" : p.text3,
+              color: draft.trim() && reachable && !sending ? "#fff" : p.text3,
               display: "flex",
               alignItems: "center",
               justifyContent: "center",
             }}
           >
-            {uploading ? (
-              <span style={{ fontSize: 10, fontWeight: 600 }}>↑</span>
-            ) : (
-              Icons.send({ size: 16 })
-            )}
+            {Icons.send({ size: 16 })}
           </button>
         </div>
       </div>

canvas/src/components/mobile/MobileComms.tsx

@@ -218,6 +218,7 @@ export function MobileComms({ dark }: { dark: boolean }) {
               key={o.id}
               type="button"
               onClick={() => setFilter(o.id)}
+              className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
               style={{
                 display: "inline-flex",
                 alignItems: "center",

canvas/src/components/mobile/MobileDetail.tsx

@@ -83,11 +83,12 @@ export function MobileDetail({
             type="button"
             onClick={onBack}
             aria-label="Back"
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={iconButtonStyle(p, dark)}
           >
             {Icons.back({ size: 18 })}
           </button>
-          <button type="button" aria-label="More" style={iconButtonStyle(p, dark)}>
+          <button type="button" aria-label="More" className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900" style={iconButtonStyle(p, dark)}>
             {Icons.more({ size: 18 })}
           </button>
         </div>
@@ -183,6 +184,7 @@ export function MobileDetail({
               key={t.id}
               type="button"
               onClick={() => setTab(t.id)}
+              className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
               style={{
                 padding: "8px 14px",
                 borderRadius: 999,
@@ -215,6 +217,7 @@ export function MobileDetail({
           type="button"
           onClick={onChat}
           data-testid="mobile-chat-cta"
+          className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
           style={{
             width: "100%",
             height: 52,

canvas/src/components/mobile/MobileHome.tsx

@@ -183,6 +183,7 @@ export function MobileHome({
         type="button"
         onClick={onSpawn}
         aria-label="Spawn new agent"
+        className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
         style={{
           position: "absolute",
           right: 24,

canvas/src/components/mobile/MobileMe.tsx

@@ -83,6 +83,7 @@ export function MobileMe({
                   type="button"
                   onClick={() => setAccent(c)}
                   aria-label={`Set accent ${c}`}
+                  className="focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
                   style={{
                     width: 36,
                     height: 36,
@@ -173,6 +174,7 @@ function SegmentedRow({
             key={o.id}
             type="button"
             onClick={() => onChange(o.id)}
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               flex: 1,
               padding: "10px 8px",

canvas/src/components/mobile/MobileSpawn.tsx

@@ -12,6 +12,7 @@ import { useEffect, useState } from "react";
 
 import { api } from "@/lib/api";
 import { type Template } from "@/lib/deploy-preflight";
+import { isSaaSTenant } from "@/lib/tenant";
 
 import { tierCode } from "./palette";
 import { MOBILE_FONT_MONO, MOBILE_FONT_SANS, type MobilePalette, usePalette } from "./palette";
@@ -26,6 +27,7 @@ const TIER_LABEL: Record<"T1" | "T2" | "T3" | "T4", string> = {
 
 export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => void }) {
   const p = usePalette(dark);
+  const isSaaS = isSaaSTenant();
   const [templates, setTemplates] = useState<Template[]>([]);
   const [loadingTemplates, setLoadingTemplates] = useState(true);
   const [tplId, setTplId] = useState<string | null>(null);
@@ -43,7 +45,7 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
         setTemplates(list);
         if (list.length > 0) {
           setTplId(list[0].id);
-          setTier(tierCode(list[0].tier));
+          setTier(isSaaS ? "T4" : tierCode(list[0].tier));
         }
       })
       .catch(() => {
@@ -55,7 +57,7 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
     return () => {
       cancelled = true;
     };
-  }, []);
+  }, [isSaaS]);
 
   const handleSpawn = async () => {
     if (busy || !tplId) return;
@@ -67,7 +69,7 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
       await api.post<{ id: string }>("/workspaces", {
         name: (name.trim() || chosen.name),
         template: chosen.id,
-        tier: Number(tier.slice(1)),
+        tier: isSaaS ? 4 : Number(tier.slice(1)),
         canvas: {
           x: Math.random() * 400 + 100,
           y: Math.random() * 300 + 100,
@@ -146,6 +148,7 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
             type="button"
             onClick={onClose}
             aria-label="Close"
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               width: 32,
               height: 32,
@@ -203,15 +206,17 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
             >
               {templates.map((t) => {
                 const on = tplId === t.id;
-                const tCode = tierCode(t.tier);
+                const tCode = isSaaS ? "T4" : tierCode(t.tier);
                 return (
                   <button
                     key={t.id}
                     type="button"
+                    aria-label={`Select template: ${t.name} (tier ${t.tier})`}
                     onClick={() => {
                       setTplId(t.id);
                       setTier(tCode);
                     }}
+                    className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
                     style={{
                       background: on
                         ? dark
@@ -327,7 +332,10 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
               <button
                 key={t}
                 type="button"
+                aria-label={`Select tier ${t}: ${TIER_LABEL[t]}`}
+                aria-pressed={tier === t}
                 onClick={() => setTier(t)}
+                className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
                 style={{
                   flex: 1,
                   padding: "10px 8px",
@@ -373,8 +381,10 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
         <div style={{ padding: "20px 14px max(env(safe-area-inset-bottom), 28px)" }}>
           <button
             type="button"
+            aria-label="Spawn agent"
             onClick={handleSpawn}
             disabled={busy || !tplId || templates.length === 0}
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               width: "100%",
               height: 52,

canvas/src/components/mobile/__tests__/MobileChat.test.tsx

@@ -358,7 +358,7 @@ describe("MobileChat — chat history", () => {
       renderChat(mockAgentId);
     });
     expect(api.get).toHaveBeenCalledWith(
-      expect.stringContaining(`/workspaces/${mockAgentId}/chat-history`),
+      `/workspaces/${mockAgentId}/chat-history?limit=50`,
     );
   });
 

canvas/src/components/mobile/components.tsx

@@ -133,6 +133,7 @@ export function TabBar({
             aria-label={t.label}
             onClick={() => onChange(t.id)}
             onKeyDown={(e) => handleKeyDown(e, idx)}
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               background: "none",
               border: "none",
@@ -291,6 +292,7 @@ export function AgentCard({
       data-testid="workspace-card"
       aria-label={`${agent.name}, status: ${agent.status}, tier ${agent.tier}${agent.remote ? ", remote" : ""}`}
       onClick={onClick}
+      className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
       style={{
         display: "block",
         width: "100%",
@@ -444,6 +446,7 @@ export function FilterChips({
             type="button"
             aria-checked={on}
             onClick={() => onChange(o.id)}
+            className="focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-500 focus-visible:ring-offset-1 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               display: "inline-flex",
               alignItems: "center",

canvas/src/components/tabs/ActivityTab.tsx

@@ -139,7 +139,7 @@ export function ActivityTab({ workspaceId }: Props) {
               key={f.id}
               onClick={() => setFilter(f.id)}
               aria-pressed={filter === f.id}
-              className={`px-2 py-1 text-[11px] rounded-md font-medium transition-all ${
+              className={`px-2 py-1 text-[11px] rounded-md font-medium transition-all focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${
                 filter === f.id
                   ? "bg-surface-card text-ink ring-1 ring-zinc-600"
                   : "text-ink-mid hover:text-ink-mid hover:bg-surface-card/60"
@@ -152,7 +152,7 @@ export function ActivityTab({ workspaceId }: Props) {
             <button
               onClick={() => setAutoRefresh(!autoRefresh)}
               aria-pressed={autoRefresh}
-              className={`text-[11px] px-1.5 py-0.5 rounded ${
+              className={`text-[11px] px-1.5 py-0.5 rounded focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${
                 autoRefresh ? "text-good bg-emerald-950/30" : "text-ink-mid"
               }`}
               title={autoRefresh ? "Auto-refresh ON" : "Auto-refresh OFF"}
@@ -161,8 +161,9 @@ export function ActivityTab({ workspaceId }: Props) {
             </button>
             <button
               onClick={() => setTraceOpen(true)}
-              className="px-2 py-1 bg-blue-900/40 hover:bg-blue-800/50 text-[11px] rounded text-accent border border-blue-800/30"
-              title="View full conversation trace across all workspaces"
+              aria-label="Full trace"
+              className="px-2 py-1 bg-blue-900/40 hover:bg-blue-800/50 text-[11px] rounded text-accent border border-blue-800/30 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
+              title="View full conversation trace"
             >
               Full Trace
             </button>

canvas/src/components/tabs/ChannelsTab.tsx

@@ -331,8 +331,9 @@ export function ChannelsTab({ workspaceId }: Props) {
                                 </label>
                               ))}
                               <button
+                                aria-label={showManualInput ? "Hide manual input" : "Show manual input"}
                                 onClick={() => setShowManualInput(!showManualInput)}
-                                className="text-[10px] text-accent hover:underline"
+                                className="text-[10px] text-accent hover:underline focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
                               >
                                 {showManualInput ? "hide manual input" : "edit manually"}
                               </button>
@@ -408,15 +409,16 @@ export function ChannelsTab({ workspaceId }: Props) {
             </div>
             <div className="flex items-center gap-1.5">
               <button
+                aria-label={testing === ch.id ? "Sent!" : "Test channel"}
                 onClick={() => handleTest(ch)}
                 disabled={testing === ch.id}
-                className="text-[10px] px-2 py-0.5 rounded bg-surface-card/50 text-ink-mid hover:text-ink transition disabled:opacity-50"
+                className="text-[10px] px-2 py-0.5 rounded bg-surface-card/50 text-ink-mid hover:text-ink transition disabled:opacity-50 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
               >
                 {testing === ch.id ? "Sent!" : "Test"}
               </button>
               <button
                 onClick={() => handleToggle(ch)}
-                className={`text-[10px] px-2 py-0.5 rounded transition ${
+                className={`text-[10px] px-2 py-0.5 rounded transition focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${
                   ch.enabled
                     ? "bg-emerald-900/30 text-good hover:bg-emerald-900/50"
                     : "bg-surface-card/50 text-ink-mid hover:text-ink-mid"
@@ -425,8 +427,9 @@ export function ChannelsTab({ workspaceId }: Props) {
                 {ch.enabled ? "On" : "Off"}
               </button>
               <button
+                aria-label={`Remove ${ch.config.chat_id || ch.config.channel_id || "channel"}`}
                 onClick={() => setPendingDelete(ch)}
-                className="text-[10px] px-2 py-0.5 rounded bg-red-900/20 text-bad hover:bg-red-900/40 transition"
+                className="text-[10px] px-2 py-0.5 rounded bg-red-900/20 text-bad hover:bg-red-900/40 transition focus:outline-none focus-visible:ring-2 focus-visible:ring-red-400"
               >
                 Remove
               </button>

canvas/src/components/tabs/ChatTab.tsx

@@ -383,7 +383,8 @@ function MyChatPanel({ workspaceId, data }: Props) {
                 // ignore — user will see no change and can retry
               }
             }}
-            className="px-2 py-0.5 text-[10px] font-medium bg-accent/10 hover:bg-accent/20 text-accent rounded border border-accent/30 transition-colors shrink-0"
+            aria-label="Enable agent chat"
+            className="px-2 py-0.5 text-[10px] font-medium bg-accent/10 hover:bg-accent/20 text-accent rounded border border-accent/30 transition-colors shrink-0 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
           >
             Enable
           </button>
@@ -403,8 +404,9 @@ function MyChatPanel({ workspaceId, data }: Props) {
               Failed to load chat history: {history.loadError}
             </p>
             <button
+              aria-label="Retry loading chat history"
               onClick={history.loadInitial}
-              className="text-[10px] px-2 py-0.5 rounded bg-red-800 text-red-200 hover:bg-red-700 transition-colors"
+              className="text-[10px] px-2 py-0.5 rounded bg-red-800 text-red-200 hover:bg-red-700 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-red-400"
             >
               Retry
             </button>
@@ -599,8 +601,9 @@ function MyChatPanel({ workspaceId, data }: Props) {
             <span className="text-[10px] text-red-300">{displayError}</span>
             {!isOnline && (
               <button
+                aria-label="Restart workspace"
                 onClick={() => setConfirmRestart(true)}
-                className="text-[11px] px-2 py-0.5 bg-red-800 text-red-200 rounded hover:bg-red-700"
+                className="text-[11px] px-2 py-0.5 bg-red-800 text-red-200 rounded hover:bg-red-700 focus:outline-none focus-visible:ring-2 focus-visible:ring-red-400"
               >
                 Restart
               </button>
@@ -636,7 +639,7 @@ function MyChatPanel({ workspaceId, data }: Props) {
             disabled={!agentReachable || sending || uploading}
             aria-label="Attach file"
             title="Attach file"
-            className="p-2 bg-surface-card hover:bg-surface-card border border-line rounded-lg text-ink-mid hover:text-ink transition-colors shrink-0 disabled:opacity-40"
+            className="p-2 bg-surface-card hover:bg-surface-card border border-line rounded-lg text-ink-mid hover:text-ink transition-colors shrink-0 disabled:opacity-40 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
           >
             <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
               <path d="M11 6.5 7 10.5a2 2 0 1 0 2.8 2.8l4-4a3.5 3.5 0 0 0-5-5l-4.5 4.5a5 5 0 0 0 7 7l4-4" stroke="currentColor" strokeWidth="1.4" strokeLinecap="round" strokeLinejoin="round" />
@@ -674,9 +677,10 @@ function MyChatPanel({ workspaceId, data }: Props) {
             className="flex-1 bg-surface-card border border-line rounded-lg px-3 py-2 text-xs text-ink placeholder-ink-soft dark:bg-zinc-800 dark:border-zinc-600 dark:placeholder-zinc-500 focus:outline-none focus:border-accent focus-visible:ring-2 focus-visible:ring-accent/40 resize-none disabled:opacity-50"
           />
           <button
+            aria-label="Send message"
             onClick={handleSend}
             disabled={(!input.trim() && pendingFiles.length === 0) || !agentReachable || sending || uploading}
-            className="px-4 py-2 bg-accent-strong hover:bg-accent text-xs font-medium rounded-lg text-white disabled:opacity-30 transition-colors shrink-0"
+            className="px-4 py-2 bg-accent-strong hover:bg-accent text-xs font-medium rounded-lg text-white disabled:opacity-30 transition-colors shrink-0 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
           >
             {uploading ? "Uploading…" : "Send"}
           </button>

canvas/src/components/tabs/ConfigTab.tsx

@@ -176,7 +176,7 @@ export function deriveProvidersFromModels(models: ModelSpec[]): string[] {
 // exactly the point of the platform adaptor. The deep `~/.hermes/
 // config.yaml` on the container is a separate runtime-internal file,
 // not this one.
-const RUNTIMES_WITH_OWN_CONFIG = new Set<string>(["external", "kimi", "kimi-cli"]);
+const RUNTIMES_WITH_OWN_CONFIG = new Set<string>(["external", "kimi", "kimi-cli", "openclaw"]);
 
 const FALLBACK_RUNTIME_OPTIONS: RuntimeOption[] = [
   { value: "", label: "LangGraph (default)", models: [], providers: [] },

canvas/src/components/tabs/FilesTab.tsx

@@ -45,11 +45,54 @@ export function FilesTab({ workspaceId, data }: Props) {
   if (data && isExternalLikeRuntime(data.runtime)) {
     return <NotAvailablePanel runtime={data.runtime} />;
   }
-  return <PlatformOwnedFilesTab workspaceId={workspaceId} />;
+  return <PlatformOwnedFilesTab workspaceId={workspaceId} runtime={data?.runtime} />;
 }
 
-function PlatformOwnedFilesTab({ workspaceId }: { workspaceId: string }) {
-  const [root, setRoot] = useState("/configs");
+/** Picks the initial root for the FilesTab dropdown based on the
+ *  workspace's runtime. Decision: per-runtime default (Hongming
+ *  2026-05-15, internal#425 Decisions §2).
+ *
+ *  - openclaw → `/agent-home` (the agent's identity/state — the
+ *    user-facing interesting files for that runtime live in
+ *    `~/.openclaw/` inside the container, which `/agent-home` maps to
+ *    via the Phase 2b docker-exec backend).
+ *  - everything else (claude-code, hermes, external-like, undefined)
+ *    → `/configs` (the legacy default — managed config that flows
+ *    through the per-runtime indirection in
+ *    workspace-server/internal/handlers/template_files_eic.go).
+ *
+ *  When the runtime is undefined (legacy callers that don't thread
+ *  `data` through, or a workspace whose runtime field hasn't loaded
+ *  yet) the default is `/configs` — matches today's behaviour, no
+ *  surprise.
+ *
+ *  Note on `/agent-home` pre-Phase-2b: the backend short-circuits
+ *  with HTTP 501 and the canonical "implementation pending" body.
+ *  The tab renders empty + the error banner explains. This is by
+ *  design — lets us land the canvas UX before the backend ships,
+ *  per the RFC's phased rollout. The 501 is graceful: it doesn't
+ *  poison error toasts or generate "workspace not found" noise.
+ *
+ *  Adding a new runtime that should default to `/agent-home`: add it
+ *  to the agentHomeDefaultRuntimes set below. Adding a runtime that
+ *  should default to a different root: extend this function. */
+const agentHomeDefaultRuntimes = new Set(["openclaw"]);
+
+function defaultRootForRuntime(runtime: string | undefined): string {
+  if (runtime && agentHomeDefaultRuntimes.has(runtime)) {
+    return "/agent-home";
+  }
+  return "/configs";
+}
+
+function PlatformOwnedFilesTab({
+  workspaceId,
+  runtime,
+}: {
+  workspaceId: string;
+  runtime?: string;
+}) {
+  const [root, setRoot] = useState(() => defaultRootForRuntime(runtime));
   const [selectedFile, setSelectedFile] = useState<string | null>(null);
   const [fileContent, setFileContent] = useState("");
   const [editContent, setEditContent] = useState("");

canvas/src/components/tabs/FilesTab/FileEditor.tsx

@@ -3,6 +3,22 @@
 import { useRef } from "react";
 import { getIcon } from "./tree";
 
+// secretShapeMarker is the canonical body the workspace-server Files
+// API returns when a file's path OR content matched a credential
+// regex (internal#425 RFC, Phase 2b — backed by
+// workspace-server/internal/secrets.ScanBytes). The marker is a
+// fixed prefix so the canvas can detect it without parsing JSON and
+// without round-tripping the matched bytes through the editor (which
+// would defeat the purpose — clipboard, browser history, log
+// surfaces would all see them).
+//
+// Today (Phase 1 / before 2b ships) the backend returns 501 for the
+// only root that uses this path, so the marker is dead code until
+// 2b lands. Wiring it in now keeps the canvas + backend contracts
+// aligned in one PR rather than a follow-up. The constant is
+// importable so a future test can pin the exact string.
+export const SECRET_SHAPE_DENIED_MARKER = "<denied: secret-shape>";
+
 interface Props {
   selectedFile: string | null;
   fileContent: string;
@@ -31,6 +47,22 @@ export function FileEditor({
   const editorRef = useRef<HTMLTextAreaElement>(null);
   const isDirty = editContent !== fileContent;
 
+  // internal#425 Phase 3: detect the secret-shape denial marker and
+  // render a placeholder instead of the editor. The marker comes
+  // from workspace-server Phase 2b (secrets.ScanBytes) which refuses
+  // to surface the file's bytes. We deliberately don't expose
+  // the matched pattern's Name here — the canvas just shows the
+  // generic denial. The Files API log surface has the Pattern.Name
+  // for operators who need to debug a false positive.
+  const isSecretShapeDenied = fileContent === SECRET_SHAPE_DENIED_MARKER;
+
+  // /agent-home is read-only from the canvas (Phase 2b ships read +
+  // delete; Phase-2b-followup may add write). Edits to /configs are
+  // unchanged. Until 2b ships, /agent-home returns 501 so this
+  // read-only gate is also dead code, but wiring it in now keeps
+  // the UI honest the moment 2b lands without a follow-up canvas PR.
+  const isReadOnlyRoot = root !== "/configs";
+
   if (!selectedFile) {
     return (
       <div className="flex-1 flex items-center justify-center">
@@ -56,7 +88,7 @@ export function FileEditor({
           <button
             onClick={onDownload}
             aria-label="Download file"
-            className="text-[10px] text-ink-mid hover:text-ink-mid"
+            className="text-[10px] text-ink-mid hover:text-ink-mid focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 rounded transition-colors"
           >
             ↓
           </button>
@@ -64,7 +96,7 @@ export function FileEditor({
             <button
               onClick={onSave}
               disabled={!isDirty || saving}
-              className="text-[10px] text-accent hover:text-accent disabled:opacity-30"
+              className="text-[10px] text-accent hover:text-accent disabled:opacity-30 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 rounded transition-colors"
             >
               {saving ? "Saving..." : "Save"}
             </button>
@@ -75,11 +107,42 @@ export function FileEditor({
       {/* Editor area */}
       {loadingFile ? (
         <div className="p-4 text-xs text-ink-mid">Loading...</div>
+      ) : isSecretShapeDenied ? (
+        // Files API refused to surface this file's bytes because its
+        // path or content matched a credential regex
+        // (workspace-server/internal/secrets, internal#425 Phase 2b).
+        // We render a placeholder INSTEAD OF the textarea so the
+        // matched bytes never enter the DOM. Clipboard / view-source
+        // / element-inspector all see the placeholder, not the
+        // credential.
+        <div
+          role="region"
+          aria-label="File content denied"
+          className="flex-1 flex items-center justify-center p-6 bg-surface"
+        >
+          <div className="max-w-md text-center space-y-2">
+            <div className="text-2xl opacity-40">🛡️</div>
+            <p className="text-[11px] font-mono text-warm">
+              {SECRET_SHAPE_DENIED_MARKER}
+            </p>
+            <p className="text-[10px] text-ink-mid leading-relaxed">
+              The platform refused to surface this file because its
+              path or content matched a credential-shape pattern.
+              The bytes never left the workspace container.
+            </p>
+            <p className="text-[10px] text-ink-mid leading-relaxed">
+              If this is a false positive (test fixture, docs example,
+              or content that happens to share a credential's shape),
+              rename the file or adjust the content via the workspace
+              terminal so the regex no longer matches, then refresh.
+            </p>
+          </div>
+        </div>
       ) : (
         <textarea
           ref={editorRef}
           value={editContent}
-          readOnly={root !== "/configs"}
+          readOnly={isReadOnlyRoot}
           onChange={(e) => setEditContent(e.target.value)}
           onKeyDown={(e) => {
             if ((e.metaKey || e.ctrlKey) && e.key === "s") {

canvas/src/components/tabs/FilesTab/FilesToolbar.tsx

@@ -38,6 +38,15 @@ export function FilesToolbar({
           <option value="/home">/home</option>
           <option value="/workspace">/workspace</option>
           <option value="/plugins">/plugins</option>
+          {/* internal#425 Phase 1+3: container-internal $HOME root.
+              Backend lands the docker-exec dispatch in Phase 2b. Until
+              then the stub returns 501 with a canonical
+              "implementation pending" message — the dropdown renders
+              the option so the canvas affordance is design-frozen
+              even before the backend ships.
+              Runtime-default selection logic in FilesTab.tsx picks
+              this as the initial value for openclaw workspaces. */}
+          <option value="/agent-home">/agent-home</option>
         </select>
         <span className="text-[10px] text-ink-mid">{fileCount} files</span>
       </div>

canvas/src/components/tabs/FilesTab/__tests__/FileTree.render-a11y.test.tsx

@@ -0,0 +1,288 @@
+// @vitest-environment jsdom
+/**
+ * Tests for FileTree — complements FileTreeContextMenu.test.tsx with:
+ *   - Empty tree render
+ *   - File row: icon, name, selection highlight
+ *   - Directory row: folder icon, expand/collapse chevron, loading indicator
+ *   - Directory expand/collapse via click
+ *   - File select callback
+ *   - Delete button: aria-label, stopPropagation
+ *   - Drop-target highlight (drag hover)
+ *   - Context menu opens on right-click
+ *   - Nested tree: recursive rendering
+ *   - WCAG: aria-label on all interactive elements
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent, createEvent, cleanup } from "@testing-library/react";
+
+// ── Mock FileTreeContextMenu (rendered by FileTree on right-click) ─────────────
+vi.mock("../FileTreeContextMenu", () => ({
+  FileTreeContextMenu: ({ items }: { items: Array<{ id: string; label: string; disabled?: boolean }>; onClose: () => void }) => (
+    <div data-testid="file-context-menu">
+      {items.map((item, i) => (
+        <button key={item.id} data-menu-id={item.id} role="menuitem" disabled={item.disabled}>
+          {item.label}
+        </button>
+      ))}
+    </div>
+  ),
+}));
+
+// ── Import component + types AFTER mocks ────────────────────────────────────────
+import { FileTree } from "../FileTree";
+import type { TreeNode } from "../tree";
+
+afterEach(() => {
+  cleanup();
+  vi.clearAllMocks();
+});
+
+// ── Test helpers ───────────────────────────────────────────────────────────────
+const makeNode = (
+  name: string,
+  opts: Partial<{
+    isDir: boolean;
+    path: string;
+    children: TreeNode[];
+  }>
+): TreeNode => ({
+  name,
+  path: opts.path ?? `/${name}`,
+  isDir: opts.isDir ?? false,
+  children: opts.children ?? [],
+  size: 0,
+});
+
+const EMPTY_CALLBACKS = {
+  selectedPath: null as string | null,
+  onSelect: vi.fn(),
+  onDelete: vi.fn(),
+  onDownload: vi.fn(),
+  canDelete: true,
+  expandedDirs: new Set<string>(),
+  onToggleDir: vi.fn(),
+  loadingDir: null as string | null,
+};
+
+describe("FileTree — empty render", () => {
+  it("renders nothing when nodes is an empty array", () => {
+    render(<FileTree nodes={[]} {...EMPTY_CALLBACKS} />);
+    expect(document.body.textContent).toBe("");
+  });
+});
+
+describe("FileTree — file row", () => {
+  it("renders a file row with the file name", () => {
+    const file = makeNode("config.yaml", { isDir: false });
+    render(<FileTree nodes={[file]} {...EMPTY_CALLBACKS} />);
+    expect(screen.getByText("config.yaml")).toBeTruthy();
+  });
+
+  it("renders file icon via getIcon (📜 for .yaml)", () => {
+    const file = makeNode("README.md", { isDir: false });
+    render(<FileTree nodes={[file]} {...EMPTY_CALLBACKS} />);
+    // Icon is a span with the emoji
+    const icon = document.querySelector('[class*="gap-1"] span');
+    expect(icon?.textContent).toBeTruthy();
+  });
+
+  it("file row has aria-label on the delete button", () => {
+    const file = makeNode("script.py", { isDir: false });
+    render(<FileTree nodes={[file]} {...EMPTY_CALLBACKS} />);
+    const delBtn = document.querySelector('button[aria-label="Delete script.py"]');
+    expect(delBtn).toBeTruthy();
+  });
+
+  it("clicking a file row calls onSelect with the file path", () => {
+    const onSelect = vi.fn();
+    const file = makeNode("app.ts", { path: "/src/app.ts", isDir: false });
+    render(<FileTree nodes={[file]} {...EMPTY_CALLBACKS} selectedPath={null} onSelect={onSelect} />);
+    fireEvent.click(screen.getByText("app.ts"));
+    expect(onSelect).toHaveBeenCalledWith("/src/app.ts");
+  });
+
+  it("selected file has different background class than unselected", () => {
+    const file = makeNode("main.py", { isDir: false });
+    render(<FileTree nodes={[file]} {...EMPTY_CALLBACKS} selectedPath="/main.py" />);
+    const row = document.querySelector('[class*="cursor-pointer"]') as HTMLElement;
+    expect(row).toBeTruthy();
+    // bg-blue-900/30 is applied when selected
+    expect(row.className).toContain("bg-blue-900/30");
+  });
+
+  it("clicking the delete button calls onDelete (stops propagation)", () => {
+    const onSelect = vi.fn();
+    const onDelete = vi.fn();
+    const file = makeNode("temp.txt", { isDir: false });
+    render(<FileTree nodes={[file]} {...EMPTY_CALLBACKS} onSelect={onSelect} onDelete={onDelete} />);
+    const delBtn = screen.getByRole("button", { name: /Delete temp\.txt/i });
+    fireEvent.click(delBtn);
+    expect(onDelete).toHaveBeenCalledWith("/temp.txt");
+    // onSelect should NOT be called (stopPropagation)
+    expect(onSelect).not.toHaveBeenCalled();
+  });
+});
+
+describe("FileTree — directory row", () => {
+  it("renders a directory row with 📁 icon and directory name", () => {
+    const dir = makeNode("src", { isDir: true, path: "/src" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} />);
+    expect(screen.getByText("src")).toBeTruthy();
+    expect(screen.getByText("📁")).toBeTruthy();
+  });
+
+  it("directory shows ▶ chevron when collapsed", () => {
+    const dir = makeNode("lib", { isDir: true, path: "/lib" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} expandedDirs={new Set()} />);
+    // collapsed → ▶
+    expect(screen.getByText("▶")).toBeTruthy();
+  });
+
+  it("directory shows ▼ chevron when expanded", () => {
+    const dir = makeNode("lib", { isDir: true, path: "/lib" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} expandedDirs={new Set(["/lib"])} />);
+    expect(screen.getByText("▼")).toBeTruthy();
+  });
+
+  it("directory shows … (loading indicator) when loadingDir matches", () => {
+    const dir = makeNode("pkg", { isDir: true, path: "/pkg" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} loadingDir="/pkg" expandedDirs={new Set(["/pkg"])} />);
+    expect(screen.getByText("…")).toBeTruthy();
+    // Chevron is replaced by loading indicator
+    expect(screen.queryByText("▼")).toBeNull();
+  });
+
+  it("clicking a collapsed directory calls onToggleDir", () => {
+    const onToggleDir = vi.fn();
+    const dir = makeNode("docs", { isDir: true, path: "/docs" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} expandedDirs={new Set()} onToggleDir={onToggleDir} />);
+    fireEvent.click(screen.getByText("docs"));
+    expect(onToggleDir).toHaveBeenCalledWith("/docs");
+  });
+
+  it("clicking an expanded directory calls onToggleDir to collapse", () => {
+    const onToggleDir = vi.fn();
+    const dir = makeNode("docs", { isDir: true, path: "/docs" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} expandedDirs={new Set(["/docs"])} onToggleDir={onToggleDir} />);
+    fireEvent.click(screen.getByText("docs"));
+    expect(onToggleDir).toHaveBeenCalledWith("/docs");
+  });
+
+  it("expanded directory renders its children recursively", () => {
+    const childFile = makeNode("index.ts", { isDir: false, path: "/src/index.ts" });
+    const dir = makeNode("src", { isDir: true, path: "/src", children: [childFile] });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} expandedDirs={new Set(["/src"])} />);
+    expect(screen.getByText("index.ts")).toBeTruthy();
+  });
+
+  it("collapsed directory does NOT render its children", () => {
+    const childFile = makeNode("inner.ts", { isDir: false, path: "/outer/inner.ts" });
+    const dir = makeNode("outer", { isDir: true, path: "/outer", children: [childFile] });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} expandedDirs={new Set()} />);
+    expect(screen.queryByText("inner.ts")).toBeNull();
+  });
+
+  it("directory delete button calls onDelete", () => {
+    const onDelete = vi.fn();
+    const dir = makeNode("cache", { isDir: true, path: "/cache" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} onDelete={onDelete} />);
+    const delBtn = screen.getByRole("button", { name: /Delete cache/i });
+    fireEvent.click(delBtn);
+    expect(onDelete).toHaveBeenCalledWith("/cache");
+  });
+
+  it("directory delete button in context menu is disabled when canDelete=false", () => {
+    const dir = makeNode("locked", { isDir: true, path: "/locked" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} canDelete={false} />);
+    // Right-click to open context menu
+    const row = document.querySelector('[class*="cursor-pointer"]') as HTMLElement;
+    fireEvent.contextMenu(row);
+    // Query inside the context menu — use role=menuitem (real component uses this)
+    // and verify the disabled attribute (vitest-compatible, no jest-dom needed)
+    const ctxMenu = screen.getByTestId("file-context-menu");
+    const delBtn = ctxMenu.querySelector('button[role="menuitem"]') as HTMLButtonElement | null;
+    expect(delBtn).not.toBeNull();
+    expect(delBtn!.disabled).toBe(true);
+  });
+});
+
+describe("FileTree — context menu", () => {
+  it("right-clicking a file opens the context menu", () => {
+    const file = makeNode("data.json", { isDir: false });
+    render(<FileTree nodes={[file]} {...EMPTY_CALLBACKS} />);
+    const row = document.querySelector('[class*="cursor-pointer"]') as HTMLElement;
+    fireEvent.contextMenu(row);
+    expect(screen.getByTestId("file-context-menu")).toBeTruthy();
+  });
+
+  it("context menu shows 'Open' and 'Download' for a file", () => {
+    const file = makeNode("report.csv", { isDir: false });
+    render(<FileTree nodes={[file]} {...EMPTY_CALLBACKS} />);
+    const row = document.querySelector('[class*="cursor-pointer"]') as HTMLElement;
+    fireEvent.contextMenu(row);
+    expect(screen.getByText("Open")).toBeTruthy();
+    expect(screen.getByText("Download")).toBeTruthy();
+  });
+
+  it("context menu shows only 'Delete' for a directory (no Open/Download)", () => {
+    const dir = makeNode("logs", { isDir: true, path: "/logs" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} />);
+    const row = document.querySelector('[class*="cursor-pointer"]') as HTMLElement;
+    fireEvent.contextMenu(row);
+    expect(screen.getByText("Delete")).toBeTruthy();
+    expect(screen.queryByText("Open")).toBeNull();
+    expect(screen.queryByText("Download")).toBeNull();
+  });
+});
+
+describe("FileTree — drag-drop target highlight (PR-D)", () => {
+  it("directory row handles dragOver without crashing", () => {
+    const onDropToTarget = vi.fn();
+    const dir = makeNode("dropdir", { isDir: true, path: "/dropdir" });
+    render(<FileTree nodes={[dir]} {...EMPTY_CALLBACKS} onDropToTarget={onDropToTarget} expandedDirs={new Set()} />);
+    const row = document.querySelector('[class*="cursor-pointer"]') as HTMLElement;
+    expect(row).toBeTruthy();
+    // jsdom's DragEvent is not available; use RTL's createEvent + dispatchEvent
+    // and stub dataTransfer so the handler's e.dataTransfer.dropEffect = "copy"
+    // assignment inside FileTree doesn't throw.
+    const dragOverEvent = createEvent.dragOver(row);
+    Object.defineProperty(dragOverEvent, "dataTransfer", {
+      value: { dropEffect: "none" },
+    });
+    row.dispatchEvent(dragOverEvent);
+    // Component should still show the node without crashing.
+    expect(screen.queryByText("dropdir")).toBeTruthy();
+  });
+
+  it("non-directory rows do not crash when onDropToTarget is provided", () => {
+    const onDropToTarget = vi.fn();
+    const file = makeNode("data.csv", { isDir: false, path: "/data.csv" });
+    // Should render without error even with onDropToTarget (files ignore it)
+    render(<FileTree nodes={[file]} {...EMPTY_CALLBACKS} onDropToTarget={onDropToTarget} expandedDirs={new Set()} />);
+    expect(screen.getByText("data.csv")).toBeTruthy();
+  });
+});
+
+describe("FileTree — nested tree", () => {
+  it("three-level deep tree renders all three levels", () => {
+    const level3 = makeNode("deep.ts", { isDir: false, path: "/a/b/c/deep.ts" });
+    const level2 = makeNode("b", { isDir: true, path: "/a/b", children: [level3] });
+    const level1 = makeNode("a", { isDir: true, path: "/a", children: [level2] });
+    render(<FileTree nodes={[level1]} {...EMPTY_CALLBACKS} expandedDirs={new Set(["/a", "/a/b"])} />);
+    expect(screen.getByText("a")).toBeTruthy();
+    expect(screen.getByText("b")).toBeTruthy();
+    expect(screen.getByText("deep.ts")).toBeTruthy();
+  });
+
+  it("only renders expanded paths — /a expanded but /a/b collapsed hides level 3", () => {
+    const level3 = makeNode("secret.ts", { isDir: false, path: "/a/b/secret.ts" });
+    const level2 = makeNode("b", { isDir: true, path: "/a/b", children: [level3] });
+    const level1 = makeNode("a", { isDir: true, path: "/a", children: [level2] });
+    render(<FileTree nodes={[level1]} {...EMPTY_CALLBACKS} expandedDirs={new Set(["/a"])} />);
+    // "a" is expanded: shows name + "b" as a collapsed child
+    expect(screen.getByText("a")).toBeTruthy();
+    expect(screen.getByText("▶")).toBeTruthy(); // "b" is collapsed (▶ not ▼)
+    // "secret.ts" is NOT rendered because /a/b is not expanded
+    expect(screen.queryByText("secret.ts")).toBeNull();
+  });
+});

canvas/src/components/tabs/FilesTab/__tests__/agentHome.test.tsx

@@ -0,0 +1,181 @@
+// @vitest-environment jsdom
+/**
+ * Tests for the /agent-home root selector + per-runtime default-root
+ * + secret-shape denial placeholder (internal#425 Phase 3).
+ *
+ * Separate file so the diff is reviewable as a unit and the existing
+ * FilesToolbar / FileEditor / FilesTab tests don't have to grow
+ * agent-home-specific cases. Once Phase 2b lands, the read-only +
+ * 501-stub assertions here can be tightened (or moved into the main
+ * test file as the agent-home root becomes a first-class affordance).
+ */
+import React from "react";
+import { render, screen, cleanup } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { FilesToolbar } from "../FilesToolbar";
+import {
+  FileEditor,
+  SECRET_SHAPE_DENIED_MARKER,
+} from "../FileEditor";
+
+afterEach(cleanup);
+
+describe("internal#425 Phase 3 — /agent-home root selector", () => {
+  it("dropdown includes /agent-home as an option", () => {
+    // Pins the affordance is in the DOM even pre-Phase-2b — the
+    // canvas design freezes today, the backend lands the dispatch
+    // later. Without this, a future refactor that drops the option
+    // would silently regress the RFC's Phase 1 contract (canvas
+    // visibility) without breaking any other test.
+    render(
+      <FilesToolbar
+        root="/configs"
+        setRoot={vi.fn()}
+        fileCount={0}
+        onNewFile={vi.fn()}
+        onUpload={vi.fn()}
+        onDownloadAll={vi.fn()}
+        onClearAll={vi.fn()}
+        onRefresh={vi.fn()}
+      />,
+    );
+    const select = screen.getByRole("combobox", {
+      name: /file root directory/i,
+    }) as HTMLSelectElement;
+    const values = Array.from(select.options).map((o) => o.value);
+    expect(values).toContain("/agent-home");
+  });
+
+  it("dropdown shows /agent-home as the SELECTED root when prop is /agent-home", () => {
+    render(
+      <FilesToolbar
+        root="/agent-home"
+        setRoot={vi.fn()}
+        fileCount={0}
+        onNewFile={vi.fn()}
+        onUpload={vi.fn()}
+        onDownloadAll={vi.fn()}
+        onClearAll={vi.fn()}
+        onRefresh={vi.fn()}
+      />,
+    );
+    const select = screen.getByRole("combobox", {
+      name: /file root directory/i,
+    }) as HTMLSelectElement;
+    expect(select.value).toBe("/agent-home");
+  });
+});
+
+describe("internal#425 Phase 3 — secret-shape denial placeholder", () => {
+  // Files API Phase 2b returns SECRET_SHAPE_DENIED_MARKER as the file
+  // body when the file's path or content matched a credential regex.
+  // The editor MUST render the marker as a placeholder, not pump it
+  // through the textarea — that would put the marker (and any future
+  // matched bytes if the backend contract changes) into the DOM
+  // value, clipboard, and inspector.
+
+  it("renders the denial placeholder INSTEAD of the textarea when fileContent is the marker", () => {
+    render(
+      <FileEditor
+        selectedFile="agent/.openclaw/secrets.env"
+        fileContent={SECRET_SHAPE_DENIED_MARKER}
+        editContent={SECRET_SHAPE_DENIED_MARKER}
+        setEditContent={vi.fn()}
+        loadingFile={false}
+        saving={false}
+        success={null}
+        root="/agent-home"
+        onSave={vi.fn()}
+        onDownload={vi.fn()}
+      />,
+    );
+    // Placeholder region present
+    expect(
+      screen.getByRole("region", { name: /file content denied/i }),
+    ).toBeTruthy();
+    // Marker text visible (so a debugging operator sees the canonical
+    // contract string without having to dig into the source).
+    expect(screen.getByText(SECRET_SHAPE_DENIED_MARKER)).toBeTruthy();
+    // Critically: NO textarea — the bytes never reach a controlled
+    // input. A regression that re-introduces the textarea path would
+    // make the matched marker (and any future content) selectable +
+    // copyable.
+    expect(screen.queryByRole("textbox")).toBeNull();
+  });
+
+  it("renders the textarea normally when fileContent is regular content", () => {
+    render(
+      <FileEditor
+        selectedFile="config.yaml"
+        fileContent="name: openclaw\n"
+        editContent="name: openclaw\n"
+        setEditContent={vi.fn()}
+        loadingFile={false}
+        saving={false}
+        success={null}
+        root="/configs"
+        onSave={vi.fn()}
+        onDownload={vi.fn()}
+      />,
+    );
+    expect(screen.getByRole("textbox")).toBeTruthy();
+    expect(screen.queryByRole("region", { name: /file content denied/i }))
+      .toBeNull();
+  });
+
+  it("/agent-home renders textarea READ-ONLY for non-denied content", () => {
+    // Phase 2b ships read + delete on /agent-home; write semantics
+    // are decided later. Until then, the canvas presents the editor
+    // as read-only so a user can't type into a buffer that the
+    // backend will refuse to PUT. Without this gate, the user would
+    // edit, hit Save, get a 501, and lose their context for why.
+    render(
+      <FileEditor
+        selectedFile=".openclaw/agent-card.json"
+        fileContent='{"name":"openclaw"}'
+        editContent='{"name":"openclaw"}'
+        setEditContent={vi.fn()}
+        loadingFile={false}
+        saving={false}
+        success={null}
+        root="/agent-home"
+        onSave={vi.fn()}
+        onDownload={vi.fn()}
+      />,
+    );
+    const textarea = screen.getByRole("textbox") as HTMLTextAreaElement;
+    expect(textarea.readOnly).toBe(true);
+  });
+
+  it("/configs renders textarea WRITABLE (regression guard for the read-only gate)", () => {
+    render(
+      <FileEditor
+        selectedFile="config.yaml"
+        fileContent="name: x\n"
+        editContent="name: x\n"
+        setEditContent={vi.fn()}
+        loadingFile={false}
+        saving={false}
+        success={null}
+        root="/configs"
+        onSave={vi.fn()}
+        onDownload={vi.fn()}
+      />,
+    );
+    const textarea = screen.getByRole("textbox") as HTMLTextAreaElement;
+    expect(textarea.readOnly).toBe(false);
+  });
+});
+
+describe("internal#425 Phase 3 — marker constant is the canonical string", () => {
+  // The marker string is part of the canvas <-> workspace-server
+  // contract. The workspace-server emits this exact body; the canvas
+  // detects it by exact-equality. A typo on either side would
+  // silently break detection — the canvas would render the literal
+  // string in the textarea instead of the placeholder. Pin the
+  // contract value here.
+  it("matches the contract value '<denied: secret-shape>'", () => {
+    expect(SECRET_SHAPE_DENIED_MARKER).toBe("<denied: secret-shape>");
+  });
+});

canvas/src/components/tabs/SkillsTab.tsx

@@ -325,7 +325,7 @@ export function SkillsTab({ workspaceId, data }: Props) {
           </div>
           <button
             onClick={() => setShowRegistry(true)}
-            className="rounded-full border border-violet-700/50 bg-violet-950/30 px-3 py-0.5 text-[10px] text-violet-200 hover:bg-violet-900/40 transition-colors"
+            className="rounded-full border border-violet-700/50 bg-violet-950/30 px-3 py-0.5 text-[10px] text-violet-200 hover:bg-violet-900/40 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-violet-400"
             aria-expanded="false"
             aria-controls="plugins-section"
           >
@@ -349,7 +349,7 @@ export function SkillsTab({ workspaceId, data }: Props) {
           </div>
           <button
             onClick={() => setShowRegistry(!showRegistry)}
-            className="rounded-full border border-violet-700/50 bg-violet-950/30 px-3 py-1 text-[10px] text-violet-200 hover:bg-violet-900/40 transition-colors"
+            className="rounded-full border border-violet-700/50 bg-violet-950/30 px-3 py-1 text-[10px] text-violet-200 hover:bg-violet-900/40 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-violet-400"
             aria-expanded={showRegistry}
             aria-controls="plugins-registry"
           >
@@ -401,7 +401,7 @@ export function SkillsTab({ workspaceId, data }: Props) {
                   <button
                     onClick={() => handleUninstall(p.name)}
                     disabled={uninstalling === p.name}
-                    className="shrink-0 rounded-full border border-red-800/40 bg-red-950/20 px-2 py-0.5 text-[11px] text-bad hover:bg-red-900/30 disabled:opacity-30"
+                    className="shrink-0 rounded-full border border-red-800/40 bg-red-950/20 px-2 py-0.5 text-[11px] text-bad hover:bg-red-900/30 disabled:opacity-30 focus:outline-none focus-visible:ring-2 focus-visible:ring-red-400"
                   >
                     {uninstalling === p.name ? "..." : "Remove"}
                   </button>
@@ -449,7 +449,7 @@ export function SkillsTab({ workspaceId, data }: Props) {
                 <button
                   onClick={handleInstallCustom}
                   disabled={!customSource.trim() || installing !== null}
-                  className="shrink-0 rounded-full border border-violet-700/50 bg-violet-950/30 px-2.5 py-1 text-[11px] text-violet-300 hover:bg-violet-900/40 disabled:opacity-30"
+                  className="shrink-0 rounded-full border border-violet-700/50 bg-violet-950/30 px-2.5 py-1 text-[11px] text-violet-300 hover:bg-violet-900/40 disabled:opacity-30 focus:outline-none focus-visible:ring-2 focus-visible:ring-violet-400"
                 >
                   {installing === customSource.trim() ? "Installing..." : "Install"}
                 </button>
@@ -538,7 +538,7 @@ export function SkillsTab({ workspaceId, data }: Props) {
                         <button
                           onClick={() => handleInstall(p.name)}
                           disabled={installing === p.name}
-                          className="shrink-0 rounded-full border border-violet-700/50 bg-violet-950/30 px-2.5 py-0.5 text-[11px] text-violet-300 hover:bg-violet-900/40 disabled:opacity-30"
+                          className="shrink-0 rounded-full border border-violet-700/50 bg-violet-950/30 px-2.5 py-0.5 text-[11px] text-violet-300 hover:bg-violet-900/40 disabled:opacity-30 focus:outline-none focus-visible:ring-2 focus-visible:ring-violet-400"
                         >
                           {installing === p.name ? "Installing..." : "Install"}
                         </button>
@@ -570,13 +570,13 @@ export function SkillsTab({ workspaceId, data }: Props) {
         <div className="mt-3 flex flex-wrap gap-2">
           <button
             onClick={() => setPanelTab("config")}
-            className="rounded-full border border-line bg-surface px-3 py-1 text-[10px] text-ink-mid hover:bg-surface-sunken"
+            className="rounded-full border border-line bg-surface px-3 py-1 text-[10px] text-ink-mid hover:bg-surface-sunken focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
           >
             Open Config
           </button>
           <button
             onClick={() => setPanelTab("files")}
-            className="rounded-full border border-line bg-surface px-3 py-1 text-[10px] text-ink-mid hover:bg-surface-sunken"
+            className="rounded-full border border-line bg-surface px-3 py-1 text-[10px] text-ink-mid hover:bg-surface-sunken focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
           >
             Open Files
           </button>

canvas/src/components/tabs/chat/AgentCommsPanel.tsx

@@ -405,7 +405,7 @@ export function AgentCommsPanel({ workspaceId }: { workspaceId: string }) {
         </p>
         <button
           onClick={loadInitial}
-          className="text-[10px] px-2 py-0.5 rounded bg-red-800/40 text-bad hover:bg-red-700/50 transition-colors"
+          className="text-[10px] px-2 py-0.5 rounded bg-red-800/40 text-bad hover:bg-red-700/50 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-red-400"
         >
           Retry
         </button>
@@ -610,7 +610,7 @@ function PeerTabButton({
       aria-selected={active}
       tabIndex={active ? 0 : -1}
       onClick={onClick}
-      className={`shrink-0 px-3 py-1.5 text-[10px] font-medium transition-colors whitespace-nowrap ${
+      className={`shrink-0 px-3 py-1.5 text-[10px] font-medium transition-colors whitespace-nowrap focus:outline-none focus-visible:ring-2 focus-visible:ring-cyan-400 ${
         active
           ? "border-b-2 border-cyan-500 text-cyan-200"
           : "border-b-2 border-transparent text-ink-mid hover:text-ink-mid"

canvas/src/components/tabs/chat/AttachmentViews.tsx

@@ -33,7 +33,7 @@ export function PendingAttachmentPill({
       <button
         onClick={onRemove}
         aria-label={`Remove ${file.name}`}
-        className="ml-0.5 text-ink-mid hover:text-ink transition-colors shrink-0"
+        className="ml-0.5 text-ink-mid hover:text-ink transition-colors shrink-0 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
       >
         <svg width="10" height="10" viewBox="0 0 16 16" fill="none" aria-hidden="true">
           <path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
@@ -63,7 +63,7 @@ export function AttachmentChip({
     <button
       onClick={() => onDownload(attachment)}
       title={`Download ${attachment.name}`}
-      className={`flex items-center gap-1.5 rounded-md border px-2 py-1 text-[10px] transition-colors max-w-full ${toneClasses}`}
+      className={`flex items-center gap-1.5 rounded-md border px-2 py-1 text-[10px] transition-colors max-w-full focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${toneClasses}`}
     >
       <FileGlyph className="shrink-0 opacity-70" />
       <span className="truncate">{attachment.name}</span>

canvas/src/hooks/useTemplateDeploy.tsx

@@ -8,6 +8,7 @@ import {
   type PreflightResult,
   type Template,
 } from "@/lib/deploy-preflight";
+import { isSaaSTenant } from "@/lib/tenant";
 import { MissingKeysModal } from "@/components/MissingKeysModal";
 
 /**
@@ -105,7 +106,7 @@ export function useTemplateDeploy(
         const ws = await api.post<{ id: string }>("/workspaces", {
           name: template.name,
           template: template.id,
-          tier: template.tier,
+          tier: isSaaSTenant() ? 4 : template.tier,
           canvas: coords,
           ...(model ? { model } : {}),
         });

canvas/src/lib/api.ts

@@ -8,14 +8,18 @@ import { getTenantSlug } from "./tenant";
 export const PLATFORM_URL =
   process.env.NEXT_PUBLIC_PLATFORM_URL ?? "http://localhost:8080";
 
-// 15s is long enough for slow CP queries but short enough that a
-// hung backend doesn't leave the UI spinning forever. The abort
-// propagates through AbortController so React components can observe
-// the error and render a retry affordance. Callers that know the
-// endpoint is intentionally slow (org import walks a tree of
-// workspaces with server-side pacing) can pass `timeoutMs` to
-// override.
-const DEFAULT_TIMEOUT_MS = 15_000;
+// 35s is long enough for the slowest server-side path (EIC SSH
+// tunnel for tenant EC2 file operations, bounded server-side by
+// `eicFileOpTimeout = 30 * time.Second` in
+// workspace-server/internal/handlers/template_files_eic.go) so the
+// canvas surfaces the server's real error instead of aborting first
+// with a generic timeout. Shorter values caused "Save & Restart" to
+// time out at the client before the backend returned its 5xx. The
+// abort still propagates through AbortController so React components
+// can render a retry affordance. Callers that know an endpoint is
+// intentionally slow (org import walks a tree of workspaces with
+// server-side pacing) can pass `timeoutMs` to override.
+const DEFAULT_TIMEOUT_MS = 35_000;
 
 export interface RequestOptions {
   timeoutMs?: number;

canvas/src/store/__tests__/canvas-events.test.ts

@@ -53,9 +53,10 @@ function makeStore(
   edges: Edge[] = [],
   selectedNodeId: string | null = null,
   agentMessages: Record<string, Array<{ id: string; content: string; timestamp: string }>> = {},
-  liveAnnouncement = ""
+  liveAnnouncement = "",
+  broadcastMessages: Array<{ id: string; sender: string; senderId: string; message: string; timestamp: string }> = []
 ) {
-  const state = { nodes, edges, selectedNodeId, agentMessages, liveAnnouncement };
+  const state = { nodes, edges, selectedNodeId, agentMessages, liveAnnouncement, broadcastMessages };
   const get = () => state;
   const set = vi.fn((partial: Record<string, unknown>) => {
     Object.assign(state, partial);
@@ -1013,3 +1014,149 @@ describe("handleCanvasEvent – liveAnnouncement", () => {
     expect(state.liveAnnouncement ?? "").toBe("");
   });
 });
+
+// ---------------------------------------------------------------------------
+// BROADCAST_MESSAGE
+//
+// Verifies that incoming org-wide broadcast WebSocket events are captured
+// in the store's broadcastMessages array and announced via liveAnnouncement
+// for screen readers. The Go platform already HTML-escaped the content at
+// broadcast time (OFFSEC-015 fix), so the handler renders it as-is.
+// ---------------------------------------------------------------------------
+
+describe("handleCanvasEvent – BROADCAST_MESSAGE", () => {
+  it("appends a broadcast message to broadcastMessages with correct fields", () => {
+    const { get, set, state } = makeStore();
+
+    handleCanvasEvent(
+      makeMsg({
+        event: "BROADCAST_MESSAGE",
+        workspace_id: "ws-sender",
+        payload: {
+          sender_id: "ws-ops",
+          sender: "Ops Agent",
+          message: "All systems go — deploy in 5 minutes",
+        },
+      }),
+      get,
+      set
+    );
+
+    expect(set).toHaveBeenCalledOnce();
+    const next = set.mock.calls[0][0] as { broadcastMessages: typeof state.broadcastMessages };
+    expect(next.broadcastMessages).toHaveLength(1);
+    expect(next.broadcastMessages[0].senderId).toBe("ws-ops");
+    expect(next.broadcastMessages[0].sender).toBe("Ops Agent");
+    expect(next.broadcastMessages[0].message).toBe("All systems go — deploy in 5 minutes");
+    expect(next.broadcastMessages[0].id).toBeTruthy(); // crypto.randomUUID() called
+    expect(next.broadcastMessages[0].timestamp).toBeTruthy();
+  });
+
+  it("sets liveAnnouncement with sender and truncated message", () => {
+    const { get, set } = makeStore();
+
+    handleCanvasEvent(
+      makeMsg({
+        event: "BROADCAST_MESSAGE",
+        workspace_id: "ws-sender",
+        payload: {
+          sender_id: "ws-ops",
+          sender: "Ops Agent",
+          message: "Deploy starting now",
+        },
+      }),
+      get,
+      set
+    );
+
+    const next = set.mock.calls[0][0] as { liveAnnouncement: string };
+    expect(next.liveAnnouncement).toBe("Broadcast from Ops Agent: Deploy starting now");
+  });
+
+  it("renders sender name as truncated ID when sender field is absent", () => {
+    const { get, set, state } = makeStore();
+
+    handleCanvasEvent(
+      makeMsg({
+        event: "BROADCAST_MESSAGE",
+        workspace_id: "ws-sender",
+        payload: {
+          sender_id: "ws-ops",
+          message: "Deploy starting now",
+        },
+      }),
+      get,
+      set
+    );
+
+    const next = set.mock.calls[0][0] as { broadcastMessages: typeof state.broadcastMessages };
+    expect(next.broadcastMessages[0].sender).toBe("ws-ops".slice(0, 8)); // fallback: first 8 chars of ID
+  });
+
+  it("is a no-op when message is empty string", () => {
+    const { get, set } = makeStore();
+
+    handleCanvasEvent(
+      makeMsg({
+        event: "BROADCAST_MESSAGE",
+        workspace_id: "ws-sender",
+        payload: { sender_id: "ws-ops", sender: "Ops Agent", message: "" },
+      }),
+      get,
+      set
+    );
+
+    expect(set).not.toHaveBeenCalled();
+  });
+
+  it("appends to existing broadcastMessages without replacing them", () => {
+    const { get, set, state } = makeStore([], [], null, {}, "", [
+      {
+        id: "existing-1",
+        senderId: "ws-old",
+        sender: "Old Agent",
+        message: "Previous broadcast",
+        timestamp: "2026-05-14T12:00:00Z",
+      },
+    ]);
+
+    handleCanvasEvent(
+      makeMsg({
+        event: "BROADCAST_MESSAGE",
+        workspace_id: "ws-sender",
+        payload: { sender_id: "ws-ops", sender: "Ops Agent", message: "New broadcast" },
+      }),
+      get,
+      set
+    );
+
+    const next = set.mock.calls[0][0] as { broadcastMessages: typeof state.broadcastMessages };
+    expect(next.broadcastMessages).toHaveLength(2);
+    expect(next.broadcastMessages[0].id).toBe("existing-1");
+    expect(next.broadcastMessages[1].message).toBe("New broadcast");
+  });
+
+  it("handles XSS-like content safely (content is pre-escaped by Go platform)", () => {
+    const { get, set, state } = makeStore();
+
+    // The Go platform applied html.EscapeString before sending, so the handler
+    // receives literal strings, not raw HTML. This test verifies no panic and
+    // correct storage.
+    handleCanvasEvent(
+      makeMsg({
+        event: "BROADCAST_MESSAGE",
+        workspace_id: "ws-evil",
+        payload: {
+          sender_id: "ws-evil",
+          sender: "Evil Sender",
+          message: "&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;",
+        },
+      }),
+      get,
+      set
+    );
+
+    const next = set.mock.calls[0][0] as { broadcastMessages: typeof state.broadcastMessages };
+    expect(next.broadcastMessages[0].message).toBe("&lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;");
+  });
+});

canvas/src/store/__tests__/canvas.test.ts

@@ -1224,3 +1224,45 @@ describe("moveNode", () => {
     });
   });
 });
+
+describe("useCanvasStore – broadcastMessages", () => {
+  beforeEach(() => {
+    useCanvasStore.setState({ broadcastMessages: [] });
+  });
+
+  it("consumeBroadcastMessages returns and clears all messages", () => {
+    useCanvasStore.setState({
+      broadcastMessages: [
+        { id: "m1", senderId: "ws-1", sender: "Agent 1", message: "Hello", timestamp: "2026-05-16T00:00:00Z" },
+        { id: "m2", senderId: "ws-2", sender: "Agent 2", message: "World", timestamp: "2026-05-16T00:01:00Z" },
+      ],
+    });
+    const consumed = useCanvasStore.getState().consumeBroadcastMessages();
+    expect(consumed).toHaveLength(2);
+    expect(useCanvasStore.getState().broadcastMessages).toHaveLength(0);
+  });
+
+  it("dismissBroadcastMessage removes the targeted message only", () => {
+    useCanvasStore.setState({
+      broadcastMessages: [
+        { id: "m1", senderId: "ws-1", sender: "Agent 1", message: "Hello", timestamp: "2026-05-16T00:00:00Z" },
+        { id: "m2", senderId: "ws-2", sender: "Agent 2", message: "World", timestamp: "2026-05-16T00:01:00Z" },
+        { id: "m3", senderId: "ws-3", sender: "Agent 3", message: "Bye", timestamp: "2026-05-16T00:02:00Z" },
+      ],
+    });
+    useCanvasStore.getState().dismissBroadcastMessage("m2");
+    const remaining = useCanvasStore.getState().broadcastMessages;
+    expect(remaining).toHaveLength(2);
+    expect(remaining.map((m) => m.id)).toEqual(["m1", "m3"]);
+  });
+
+  it("dismissBroadcastMessage is idempotent for unknown IDs", () => {
+    useCanvasStore.setState({
+      broadcastMessages: [
+        { id: "m1", senderId: "ws-1", sender: "Agent 1", message: "Hello", timestamp: "2026-05-16T00:00:00Z" },
+      ],
+    });
+    expect(() => useCanvasStore.getState().dismissBroadcastMessage("nonexistent")).not.toThrow();
+    expect(useCanvasStore.getState().broadcastMessages).toHaveLength(1);
+  });
+});

canvas/src/store/canvas-events.ts

@@ -72,6 +72,7 @@ export function handleCanvasEvent(
     edges: Edge[];
     selectedNodeId: string | null;
     agentMessages: Record<string, Array<{ id: string; content: string; timestamp: string; attachments?: Array<{ name: string; uri: string; mimeType?: string; size?: number }> }>>;
+    broadcastMessages: Array<{ id: string; sender: string; senderId: string; message: string; timestamp: string }>;
   },
   set: (partial: Record<string, unknown>) => void,
 ): void {
@@ -515,6 +516,34 @@ export function handleCanvasEvent(
       break;
     }
 
+    case "BROADCAST_MESSAGE": {
+      // An agent workspace sent an org-wide broadcast. Display it as a
+      // dismissible banner so the user is always aware of org-wide signals
+      // even when no workspace is selected. The Go platform already HTML-
+      // escaped the content at broadcast time (OFFSEC-015 fix), so it is
+      // safe to render as innerText equivalent via dangerouslySetInnerHTML
+      // is not needed — just render the string as-is.
+      const senderId = (msg.payload.sender_id as string) ?? "";
+      const sender = (msg.payload.sender as string) ?? senderId.slice(0, 8);
+      const message = (msg.payload.message as string) ?? "";
+      if (!message) break;
+      const { broadcastMessages } = get();
+      set({
+        broadcastMessages: [
+          ...broadcastMessages,
+          {
+            id: crypto.randomUUID(),
+            senderId,
+            sender,
+            message,
+            timestamp: new Date().toISOString(),
+          },
+        ],
+        liveAnnouncement: `Broadcast from ${sender}: ${message}`,
+      });
+      break;
+    }
+
     default:
       break;
   }

canvas/src/store/canvas.ts

@@ -244,6 +244,13 @@ interface CanvasState {
    *  so the same announcement doesn't re-fire on re-render. */
   liveAnnouncement: string;
   setLiveAnnouncement: (msg: string) => void;
+  /** Incoming org-wide broadcast messages received via BROADCAST_MESSAGE
+   *  WebSocket events. Consumed by the BroadcastBanner component; each
+   *  entry is cleared after the user dismisses it so dismissed broadcasts
+   *  don't reappear on reconnect. */
+  broadcastMessages: Array<{ id: string; sender: string; senderId: string; message: string; timestamp: string }>;
+  consumeBroadcastMessages: () => Array<{ id: string; sender: string; senderId: string; message: string; timestamp: string }>;
+  dismissBroadcastMessage: (id: string) => void;
 }
 
 export const useCanvasStore = create<CanvasState>((set, get) => ({
@@ -342,6 +349,14 @@ export const useCanvasStore = create<CanvasState>((set, get) => ({
   },
   liveAnnouncement: "",
   setLiveAnnouncement: (msg) => set({ liveAnnouncement: msg }),
+  broadcastMessages: [],
+  consumeBroadcastMessages: () => {
+    const msgs = get().broadcastMessages;
+    set({ broadcastMessages: [] });
+    return msgs;
+  },
+  dismissBroadcastMessage: (id) =>
+    set({ broadcastMessages: get().broadcastMessages.filter((m) => m.id !== id) }),
 
   viewport: { x: 0, y: 0, zoom: 1 },
 

tests/e2e/test_peer_visibility_mcp_staging.sh

@@ -0,0 +1,376 @@
+#!/usr/bin/env bash
+# Staging E2E — fresh-provision peer-visibility gate via the LITERAL MCP path.
+#
+# WHY THIS EXISTS
+# ---------------
+# Hermes and OpenClaw were repeatedly reported "fleet-verified / cascade-
+# complete" because the *proxy* signals were green:
+#   - registry-registration + heartbeat (Hermes), and
+#   - model round-trip 200 (OpenClaw).
+# But a freshly-provisioned workspace, asked on canvas "can you see your
+# peers", actually FAILS:
+#   - Hermes: 401 on the molecule MCP `list_peers` call,
+#   - OpenClaw: falls back to native `sessions_list`, sees no platform peers.
+# Tasks #142/#159 were even marked "completed" under this same proxy flaw.
+#
+# This script codifies the LITERAL user-facing path so it can never silently
+# regress: it provisions a brand-new throwaway org + sibling workspaces via
+# the real control-plane provisioning path, then for each runtime that should
+# have platform peer-visibility it drives the EXACT MCP call the canvas agent
+# makes — `POST /workspaces/:id/mcp` JSON-RPC tools/call name=list_peers,
+# authenticated by that workspace's own bearer token through the real
+# WorkspaceAuth + MCPRateLimiter middleware chain. It then asserts:
+#   (1) HTTP 200,
+#   (2) JSON-RPC `result` present (NOT an `error` object — a -32000
+#       "tool call failed" or a 401 from WorkspaceAuth fails here),
+#   (3) the returned peer set CONTAINS the other provisioned sibling
+#       workspace IDs — not an empty list, not a native-sessions fallback.
+#
+# This is NOT a proxy. It does not look at a registry row, /health, the
+# heartbeat table, or `GET /registry/:id/peers`. It drives the byte-for-byte
+# JSON-RPC envelope that mcp_molecule_list_peers issues from a real agent.
+#
+# It is written to FAIL on today's broken Hermes/OpenClaw behavior and go
+# green only when the in-flight root-cause fixes (Hermes-401, OpenClaw MCP
+# wiring) actually land. That is the point: it is the objective proof gate.
+#
+# AUTH MODEL (mirrors tests/e2e/test_staging_full_saas.sh)
+# --------------------------------------------------------
+#   Single MOLECULE_ADMIN_TOKEN (= CP_ADMIN_API_TOKEN on Railway staging)
+#   drives: POST /cp/admin/orgs (provision), GET
+#   /cp/admin/orgs/:slug/admin-token (per-tenant token), DELETE
+#   /cp/admin/tenants/:slug (teardown). The per-tenant admin token drives
+#   tenant workspace creation; each workspace's OWN auth_token (returned by
+#   POST /workspaces) drives its MCP call.
+#
+# Required env:
+#   MOLECULE_ADMIN_TOKEN   CP admin bearer — Railway staging CP_ADMIN_API_TOKEN
+# Optional env:
+#   MOLECULE_CP_URL        default https://staging-api.moleculesai.app
+#   E2E_RUN_ID             slug suffix; CI passes ${GITHUB_RUN_ID}
+#   PV_RUNTIMES            space list; default "hermes openclaw claude-code"
+#   E2E_PROVISION_TIMEOUT_SECS  default 1800 (hermes/openclaw cold EC2 budget)
+#   E2E_MINIMAX_API_KEY / E2E_ANTHROPIC_API_KEY / E2E_OPENAI_API_KEY
+#                          LLM provider key injected so the runtime can boot
+#   E2E_KEEP_ORG           1 → skip teardown (local debugging only)
+#
+# Exit codes:
+#   0  every runtime saw its peers via the literal MCP call
+#   1  generic failure
+#   2  missing required env
+#   3  provisioning timed out
+#   4  teardown left orphan resources
+#   10 peer-visibility regression reproduced (the gate firing as designed)
+
+set -uo pipefail
+
+CP_URL="${MOLECULE_CP_URL:-https://staging-api.moleculesai.app}"
+ADMIN_TOKEN="${MOLECULE_ADMIN_TOKEN:?MOLECULE_ADMIN_TOKEN required — Railway staging CP_ADMIN_API_TOKEN}"
+RUN_ID_SUFFIX="${E2E_RUN_ID:-$(date +%H%M%S)-$$}"
+PV_RUNTIMES="${PV_RUNTIMES:-hermes openclaw claude-code}"
+PROVISION_TIMEOUT_SECS="${E2E_PROVISION_TIMEOUT_SECS:-1800}"
+
+# Slug MUST start with 'e2e-' so the sweep-stale-e2e-orgs safety net
+# (EPHEMERAL_PREFIXES) catches any leak this run fails to tear down.
+SLUG="e2e-pv-$(date +%Y%m%d)-${RUN_ID_SUFFIX}"
+SLUG=$(echo "$SLUG" | tr '[:upper:]' '[:lower:]' | tr -cd 'a-z0-9-' | head -c 32)
+
+ORG_ID=""
+TENANT_URL=""
+TENANT_TOKEN=""
+
+log()  { echo "[$(date +%H:%M:%S)] $*"; }
+fail() { echo "[$(date +%H:%M:%S)] ❌ $*" >&2; exit 1; }
+ok()   { echo "[$(date +%H:%M:%S)] ✅ $*"; }
+
+admin_call() {
+  local method="$1" path="$2"; shift 2
+  curl -sS -X "$method" "$CP_URL$path" \
+    -H "Authorization: Bearer $ADMIN_TOKEN" \
+    -H "Content-Type: application/json" "$@"
+}
+tenant_call() {
+  local method="$1" path="$2"; shift 2
+  curl -sS -X "$method" "$TENANT_URL$path" \
+    -H "Authorization: Bearer $TENANT_TOKEN" \
+    -H "X-Molecule-Org-Id: $ORG_ID" \
+    -H "Content-Type: application/json" "$@"
+}
+
+# ─── Scoped teardown ───────────────────────────────────────────────────
+# Deletes ONLY the org this run created (DELETE /cp/admin/tenants/$SLUG
+# with the {"confirm":$SLUG} fat-finger guard). Never a cluster-wide
+# sweep — honors feedback_cleanup_after_each_test and
+# feedback_never_run_cluster_cleanup_tests_on_live_platform. The
+# workflow's always() step + sweep-stale-e2e-orgs are the outer nets.
+teardown() {
+  local rc=$?
+  set +e
+  if [ "${E2E_KEEP_ORG:-0}" = "1" ]; then
+    echo ""
+    log "[teardown] E2E_KEEP_ORG=1 — leaving $SLUG for debugging (REMEMBER TO DELETE)"
+    exit $rc
+  fi
+  echo ""
+  log "[teardown] DELETE /cp/admin/tenants/$SLUG (scoped to this run only)"
+  admin_call DELETE "/cp/admin/tenants/$SLUG" --max-time 120 \
+    -d "{\"confirm\":\"$SLUG\"}" >/dev/null 2>&1
+  for j in $(seq 1 24); do
+    LIST=$(admin_call GET "/cp/admin/orgs?limit=500" 2>/dev/null)
+    LEAK=$(echo "$LIST" | python3 -c "
+import sys, json
+try: d = json.load(sys.stdin)
+except Exception: print(1); sys.exit(0)
+orgs = d if isinstance(d, list) else d.get('orgs', [])
+print(sum(1 for o in orgs if o.get('slug') == '$SLUG' and o.get('instance_status') not in ('purged',) and o.get('status') != 'purged'))
+" 2>/dev/null || echo 1)
+    if [ "$LEAK" = "0" ]; then
+      log "[teardown] ✓ $SLUG purged (after ${j}x5s)"
+      exit $rc
+    fi
+    sleep 5
+  done
+  echo "::warning::[teardown] $SLUG still present after 120s — sweep-stale-e2e-orgs will catch it within MAX_AGE_MINUTES" >&2
+  [ $rc -eq 0 ] && rc=4
+  exit $rc
+}
+trap teardown EXIT INT TERM
+
+# ─── 1. Provision the throwaway org ────────────────────────────────────
+log "1/6 POST /cp/admin/orgs — slug=$SLUG"
+CREATE=$(admin_call POST /cp/admin/orgs \
+  -d "{\"slug\":\"$SLUG\",\"name\":\"E2E peer-visibility $SLUG\",\"owner_user_id\":\"e2e-runner:$SLUG\"}")
+ORG_ID=$(echo "$CREATE" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null)
+[ -n "$ORG_ID" ] || fail "org creation failed: $(echo "$CREATE" | head -c 300)"
+log "    ORG_ID=$ORG_ID"
+
+# ─── 2. Wait for tenant EC2 + DNS ──────────────────────────────────────
+log "2/6 waiting for tenant instance_status=running (cold EC2 + cloudflared)..."
+DEADLINE=$(( $(date +%s) + PROVISION_TIMEOUT_SECS ))
+while true; do
+  [ "$(date +%s)" -gt "$DEADLINE" ] && fail "tenant never came up within ${PROVISION_TIMEOUT_SECS}s"
+  STATUS=$(admin_call GET "/cp/admin/orgs?limit=500" 2>/dev/null | python3 -c "
+import sys, json
+try: d = json.load(sys.stdin)
+except Exception: sys.exit(0)
+orgs = d if isinstance(d, list) else d.get('orgs', [])
+for o in orgs:
+    if o.get('slug') == '$SLUG':
+        print(o.get('instance_status') or o.get('status') or 'unknown'); break
+" 2>/dev/null)
+  case "$STATUS" in running|online|ready) break ;; esac
+  sleep 10
+done
+log "    tenant status=$STATUS"
+
+# ─── 3. Per-tenant admin token + tenant URL ────────────────────────────
+log "3/6 fetching per-tenant admin token..."
+TT_RESP=$(admin_call GET "/cp/admin/orgs/$SLUG/admin-token")
+TENANT_TOKEN=$(echo "$TT_RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('admin_token',''))" 2>/dev/null)
+[ -n "$TENANT_TOKEN" ] || fail "tenant token fetch failed: $(echo "$TT_RESP" | head -c 200)"
+
+CP_HOST=$(echo "$CP_URL" | sed -E 's#^https?://##; s#/.*$##')
+case "$CP_HOST" in
+  api.*)         DERIVED_DOMAIN="${CP_HOST#api.}" ;;
+  staging-api.*) DERIVED_DOMAIN="staging.${CP_HOST#staging-api.}" ;;
+  *)             DERIVED_DOMAIN="$CP_HOST" ;;
+esac
+TENANT_URL="https://${SLUG}.${DERIVED_DOMAIN}"
+log "    tenant url: $TENANT_URL"
+
+log "3b. waiting for tenant /health (TLS/DNS, up to 10min)..."
+for i in $(seq 1 120); do
+  curl -fsS "$TENANT_URL/health" -m 5 -k >/dev/null 2>&1 && { log "    /health ok (attempt $i)"; break; }
+  sleep 5
+done
+
+# ─── 4. Provision the parent + one sibling per runtime under test ──────
+# Inject the LLM provider key so each runtime can authenticate at boot.
+# Priority: MiniMax → direct-Anthropic → OpenAI (mirrors
+# test_staging_full_saas.sh's secrets-injection chain).
+SECRETS_JSON='{}'
+if [ -n "${E2E_MINIMAX_API_KEY:-}" ]; then
+  SECRETS_JSON=$(python3 -c "import json,os;k=os.environ['E2E_MINIMAX_API_KEY'];print(json.dumps({'ANTHROPIC_BASE_URL':'https://api.minimax.io/anthropic','ANTHROPIC_AUTH_TOKEN':k,'MINIMAX_API_KEY':k}))")
+elif [ -n "${E2E_ANTHROPIC_API_KEY:-}" ]; then
+  SECRETS_JSON=$(python3 -c "import json,os;k=os.environ['E2E_ANTHROPIC_API_KEY'];print(json.dumps({'ANTHROPIC_API_KEY':k}))")
+elif [ -n "${E2E_OPENAI_API_KEY:-}" ]; then
+  SECRETS_JSON=$(python3 -c "import json,os;k=os.environ['E2E_OPENAI_API_KEY'];print(json.dumps({'OPENAI_API_KEY':k,'OPENAI_BASE_URL':'https://api.openai.com/v1','MODEL_PROVIDER':'openai:gpt-4o','HERMES_INFERENCE_PROVIDER':'custom','HERMES_CUSTOM_BASE_URL':'https://api.openai.com/v1','HERMES_CUSTOM_API_KEY':k,'HERMES_CUSTOM_API_MODE':'chat_completions'}))")
+fi
+
+log "4/6 provisioning parent (claude-code) + one sibling per runtime under test..."
+P_RESP=$(tenant_call POST /workspaces \
+  -d "{\"name\":\"pv-parent\",\"runtime\":\"claude-code\",\"tier\":3,\"secrets\":$SECRETS_JSON}")
+PARENT_ID=$(echo "$P_RESP" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null)
+[ -n "$PARENT_ID" ] || fail "parent create failed: $(echo "$P_RESP" | head -c 300)"
+log "    PARENT_ID=$PARENT_ID"
+
+# WS_IDS[runtime]=id ; WS_TOKENS[runtime]=auth_token (the MCP bearer)
+declare -A WS_IDS WS_TOKENS
+ALL_WS_IDS="$PARENT_ID"
+for rt in $PV_RUNTIMES; do
+  R=$(tenant_call POST /workspaces \
+    -d "{\"name\":\"pv-$rt\",\"runtime\":\"$rt\",\"tier\":2,\"parent_id\":\"$PARENT_ID\",\"secrets\":$SECRETS_JSON}")
+  WID=$(echo "$R" | python3 -c "import sys,json; print(json.load(sys.stdin).get('id',''))" 2>/dev/null)
+  # auth_token is top-level for container runtimes; external-like nest it
+  # under connection.auth_token (verified vs staging response shape).
+  WTOK=$(echo "$R" | python3 -c "
+import sys, json
+try: d = json.load(sys.stdin)
+except Exception: print(''); sys.exit(0)
+print(d.get('auth_token') or d.get('connection', {}).get('auth_token') or '')
+" 2>/dev/null)
+  [ -n "$WID" ] || fail "$rt workspace create failed: $(echo "$R" | head -c 300)"
+  [ -n "$WTOK" ] || fail "$rt workspace did not return an auth_token — cannot drive its MCP call (resp: $(echo "$R" | head -c 300))"
+  WS_IDS[$rt]="$WID"
+  WS_TOKENS[$rt]="$WTOK"
+  ALL_WS_IDS="$ALL_WS_IDS $WID"
+  log "    $rt → $WID"
+done
+
+# ─── 5. Wait for every sibling online ──────────────────────────────────
+log "5/6 waiting for all workspaces status=online (up to ${PROVISION_TIMEOUT_SECS}s — cold boot)..."
+WS_DEADLINE=$(( $(date +%s) + PROVISION_TIMEOUT_SECS ))
+for rt in $PV_RUNTIMES; do
+  wid="${WS_IDS[$rt]}"
+  LAST=""
+  while true; do
+    [ "$(date +%s)" -gt "$WS_DEADLINE" ] && fail "$rt ($wid) never reached online (last=$LAST)"
+    S=$(tenant_call GET "/workspaces/$wid" 2>/dev/null | python3 -c "
+import sys, json
+try: d = json.load(sys.stdin)
+except Exception: sys.exit(0)
+w = d.get('workspace') if isinstance(d.get('workspace'), dict) else d
+print(w.get('status') or '')
+" 2>/dev/null)
+    [ "$S" != "$LAST" ] && { log "    $rt → $S"; LAST="$S"; }
+    case "$S" in
+      online) break ;;
+      failed) sleep 10 ;;   # transient: bootstrap-watcher 5-min deadline, heartbeat recovers
+      *)      sleep 10 ;;
+    esac
+  done
+  ok "    $rt online"
+done
+
+# ─── 6. THE GATE — literal mcp_molecule_list_peers via POST /:id/mcp ────
+# This is the byte-for-byte user-facing call. NOT GET /registry/:id/peers,
+# NOT /health, NOT the heartbeat table. JSON-RPC 2.0 tools/call,
+# name=list_peers, authenticated by the workspace's OWN bearer token
+# through WorkspaceAuth + MCPRateLimiter.
+log "6/6 driving the LITERAL list_peers MCP call per runtime..."
+echo ""
+RPC_BODY='{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_peers","arguments":{}}}'
+REGRESSED=0
+declare -A VERDICT
+
+for rt in $PV_RUNTIMES; do
+  wid="${WS_IDS[$rt]}"
+  wtok="${WS_TOKENS[$rt]}"
+  # The expected peer set = every OTHER provisioned workspace (parent +
+  # the sibling runtimes), excluding the caller itself.
+  EXPECT_IDS=$(echo "$ALL_WS_IDS" | tr ' ' '\n' | grep -v "^${wid}$" | grep -v '^$')
+
+  set +e
+  RESP=$(curl -sS -X POST "$TENANT_URL/workspaces/$wid/mcp" \
+    -H "Authorization: Bearer $wtok" \
+    -H "X-Molecule-Org-Id: $ORG_ID" \
+    -H "Content-Type: application/json" \
+    -d "$RPC_BODY" \
+    -o /tmp/pv_mcp_body.json -w "%{http_code}" 2>/dev/null)
+  set -e
+  HTTP_CODE="$RESP"
+  BODY=$(cat /tmp/pv_mcp_body.json 2>/dev/null || echo '')
+
+  echo "--- $rt (ws=$wid) ---"
+  echo "    HTTP $HTTP_CODE"
+  echo "    body: $(echo "$BODY" | head -c 600)"
+
+  # (1) HTTP 200 — a 401 (WorkspaceAuth reject, the Hermes symptom) fails here.
+  if [ "$HTTP_CODE" != "200" ]; then
+    echo "  ✗ $rt: list_peers MCP call returned HTTP $HTTP_CODE (expected 200)"
+    VERDICT[$rt]="FAIL(http=$HTTP_CODE)"
+    REGRESSED=1
+    continue
+  fi
+
+  # (2) JSON-RPC result present, not an error object.
+  PARSE=$(echo "$BODY" | python3 -c "
+import sys, json
+expect = set(filter(None, '''$EXPECT_IDS'''.split()))
+try:
+    d = json.load(sys.stdin)
+except Exception as e:
+    print('PARSE_ERROR:' + str(e)); sys.exit(0)
+if isinstance(d, dict) and d.get('error') is not None:
+    print('RPC_ERROR:' + json.dumps(d['error'])[:200]); sys.exit(0)
+res = d.get('result') if isinstance(d, dict) else None
+if res is None:
+    print('NO_RESULT'); sys.exit(0)
+# MCP tools/call result shape: {content:[{type:text,text:'<json or prose>'}]}
+text = ''
+if isinstance(res, dict):
+    for c in res.get('content', []):
+        if c.get('type') == 'text':
+            text += c.get('text', '')
+text_l = text.lower()
+# Native-sessions fallback signature (the OpenClaw symptom): the agent
+# answered from its own runtime session list, not the platform peer set.
+if 'sessions_list' in text_l or 'no platform peers' in text_l or 'native session' in text_l:
+    print('NATIVE_FALLBACK:' + text[:200]); sys.exit(0)
+# The expected sibling IDs must literally appear in the returned peer text.
+found = sorted(i for i in expect if i in text)
+missing = sorted(expect - set(found))
+if not expect:
+    print('NO_EXPECTED_PEERS_CONFIGURED'); sys.exit(0)
+if missing:
+    print('MISSING_PEERS:found=%d/%d missing=%s' % (len(found), len(expect), ','.join(m[:8] for m in missing)))
+    sys.exit(0)
+print('OK:found=%d/%d' % (len(found), len(expect)))
+" 2>/dev/null)
+
+  case "$PARSE" in
+    OK:*)
+      echo "  ✓ $rt: list_peers returned 200 and contains all expected peers ($PARSE)"
+      VERDICT[$rt]="OK"
+      ;;
+    NATIVE_FALLBACK:*)
+      echo "  ✗ $rt: list_peers fell back to NATIVE sessions — sees no platform peers ($PARSE)"
+      VERDICT[$rt]="FAIL(native-fallback)"
+      REGRESSED=1
+      ;;
+    RPC_ERROR:*|NO_RESULT|PARSE_ERROR:*)
+      echo "  ✗ $rt: list_peers MCP call did not return a usable result ($PARSE)"
+      VERDICT[$rt]="FAIL(rpc=$PARSE)"
+      REGRESSED=1
+      ;;
+    MISSING_PEERS:*)
+      echo "  ✗ $rt: list_peers returned 200 but peer set is wrong/empty ($PARSE)"
+      VERDICT[$rt]="FAIL(peers=$PARSE)"
+      REGRESSED=1
+      ;;
+    *)
+      echo "  ✗ $rt: unexpected verdict '$PARSE'"
+      VERDICT[$rt]="FAIL(unknown)"
+      REGRESSED=1
+      ;;
+  esac
+  echo ""
+done
+
+echo "=== SUMMARY — fresh-provision peer-visibility (literal MCP list_peers) ==="
+for rt in $PV_RUNTIMES; do
+  printf '  %-14s %s\n' "$rt" "${VERDICT[$rt]:-NO_RUN}"
+done
+echo ""
+
+if [ "$REGRESSED" -ne 0 ]; then
+  echo "✗ GATE FAILED — at least one runtime cannot see its peers via the"
+  echo "  literal mcp_molecule_list_peers call. This is the real user-facing"
+  echo "  failure the proxy signals (registry row / heartbeat / model 200)"
+  echo "  were hiding. Expected RED until the Hermes-401 + OpenClaw-MCP-wiring"
+  echo "  root-cause fixes land; goes green only when they actually do."
+  exit 10
+fi
+
+ok "GATE PASSED — every runtime under test sees its platform peers via the literal MCP call."
+exit 0

workspace-server/internal/handlers/a2a_proxy.go

@@ -97,28 +97,28 @@ const maxProxyResponseBody = 10 << 20
 //
 // Timeout model — three independent budgets, none of which gets in each other's way:
 //
-//   1. Client.Timeout — DELIBERATELY UNSET. Client.Timeout is a hard wall on
-//      the entire request including streamed body reads, and would pre-empt
-//      legitimate slow cold-start flows (Claude Code first-token over OAuth
-//      can take 30-60s on boot; long-running agent synthesis can stream
-//      tokens for minutes). Total-request budget is enforced per-request
-//      via context deadline (canvas = idle-only, agent-to-agent = 30 min ceiling).
+//  1. Client.Timeout — DELIBERATELY UNSET. Client.Timeout is a hard wall on
+//     the entire request including streamed body reads, and would pre-empt
+//     legitimate slow cold-start flows (Claude Code first-token over OAuth
+//     can take 30-60s on boot; long-running agent synthesis can stream
+//     tokens for minutes). Total-request budget is enforced per-request
+//     via context deadline (canvas = idle-only, agent-to-agent = 30 min ceiling).
 //
-//   2. Transport.DialContext — 10s connect timeout. When a workspace's EC2
-//      black-holes TCP connects (instance terminated mid-flight, security group
-//      flipped, NACL bug), the OS default is 75s on Linux / 21s on macOS — long
-//      enough that Cloudflare's ~100s edge timeout can fire first and surface
-//      a generic 502 page to canvas. 10s is well above realistic intra-region
-//      latencies and well below CF's edge timeout.
+//  2. Transport.DialContext — 10s connect timeout. When a workspace's EC2
+//     black-holes TCP connects (instance terminated mid-flight, security group
+//     flipped, NACL bug), the OS default is 75s on Linux / 21s on macOS — long
+//     enough that Cloudflare's ~100s edge timeout can fire first and surface
+//     a generic 502 page to canvas. 10s is well above realistic intra-region
+//     latencies and well below CF's edge timeout.
 //
-//   3. Transport.ResponseHeaderTimeout — 180s default. From request-body-end
-//      to response-headers-start. Configurable via
-//      A2A_PROXY_RESPONSE_HEADER_TIMEOUT (envx.Duration). Covers cold-start
-//      first-byte (30-60s OAuth flow above) with enough room for Opus agent
-//      turns (big context + internal delegate_task round-trips routinely exceed
-//      the old 60s ceiling). Body streaming after headers is governed by the
-//      per-request context deadline, NOT this timeout — so multi-minute agent
-//      responses still work fine.
+//  3. Transport.ResponseHeaderTimeout — 180s default. From request-body-end
+//     to response-headers-start. Configurable via
+//     A2A_PROXY_RESPONSE_HEADER_TIMEOUT (envx.Duration). Covers cold-start
+//     first-byte (30-60s OAuth flow above) with enough room for Opus agent
+//     turns (big context + internal delegate_task round-trips routinely exceed
+//     the old 60s ceiling). Body streaming after headers is governed by the
+//     per-request context deadline, NOT this timeout — so multi-minute agent
+//     responses still work fine.
 //
 // The point of (2) and (3) is to surface a *structured* 503 from
 // handleA2ADispatchError when the workspace agent is unreachable, so canvas

workspace-server/internal/handlers/a2a_proxy_helpers.go

@@ -194,7 +194,7 @@ func (h *WorkspaceHandler) maybeMarkContainerDead(ctx context.Context, workspace
 	}
 	db.ClearWorkspaceKeys(ctx, workspaceID)
 	h.broadcaster.RecordAndBroadcast(ctx, string(events.EventWorkspaceOffline), workspaceID, map[string]interface{}{})
-	go h.RestartByID(workspaceID)
+	h.goAsync(func() { h.RestartByID(workspaceID) })
 	return true
 }
 
@@ -241,7 +241,7 @@ func (h *WorkspaceHandler) preflightContainerHealth(ctx context.Context, workspa
 	}
 	db.ClearWorkspaceKeys(ctx, workspaceID)
 	h.broadcaster.RecordAndBroadcast(ctx, string(events.EventWorkspaceOffline), workspaceID, map[string]interface{}{})
-	go h.RestartByID(workspaceID)
+	h.goAsync(func() { h.RestartByID(workspaceID) })
 	return &proxyA2AError{
 		Status: http.StatusServiceUnavailable,
 		Response: gin.H{
@@ -262,8 +262,8 @@ func (h *WorkspaceHandler) logA2AFailure(ctx context.Context, workspaceID, calle
 		errWsName = workspaceID
 	}
 	summary := "A2A request to " + errWsName + " failed: " + errMsg
-	go func(parent context.Context) {
-		logCtx, cancel := context.WithTimeout(context.WithoutCancel(parent), 30*time.Second)
+	h.goAsync(func() {
+		logCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
 		defer cancel()
 		LogActivity(logCtx, h.broadcaster, ActivityParams{
 			WorkspaceID:  workspaceID,
@@ -277,7 +277,7 @@ func (h *WorkspaceHandler) logA2AFailure(ctx context.Context, workspaceID, calle
 			Status:       "error",
 			ErrorDetail:  &errMsg,
 		})
-	}(ctx)
+	})
 }
 
 // logA2ASuccess records a successful A2A round-trip and (for canvas-initiated
@@ -298,19 +298,19 @@ func (h *WorkspaceHandler) logA2ASuccess(ctx context.Context, workspaceID, calle
 	// silent workspaces. Only update when callerID is a real workspace (not
 	// canvas, not a system caller) and the target returned 2xx/3xx.
 	if callerID != "" && !isSystemCaller(callerID) && statusCode < 400 {
-		go func() {
+		h.goAsync(func() {
 			bgCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
 			defer cancel()
 			if _, err := db.DB.ExecContext(bgCtx,
 				`UPDATE workspaces SET last_outbound_at = NOW() WHERE id = $1`, callerID); err != nil {
 				log.Printf("last_outbound_at update failed for %s: %v", callerID, err)
 			}
-		}()
+		})
 	}
 	summary := a2aMethod + " → " + wsNameForLog
 	toolTrace := extractToolTrace(respBody)
-	go func(parent context.Context) {
-		logCtx, cancel := context.WithTimeout(context.WithoutCancel(parent), 30*time.Second)
+	h.goAsync(func() {
+		logCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
 		defer cancel()
 		LogActivity(logCtx, h.broadcaster, ActivityParams{
 			WorkspaceID:  workspaceID,
@@ -325,7 +325,7 @@ func (h *WorkspaceHandler) logA2ASuccess(ctx context.Context, workspaceID, calle
 			DurationMs:   &durationMs,
 			Status:       logStatus,
 		})
-	}(ctx)
+	})
 
 	if callerID == "" && statusCode < 400 {
 		h.broadcaster.BroadcastOnly(workspaceID, string(events.EventA2AResponse), map[string]interface{}{
@@ -510,8 +510,8 @@ func (h *WorkspaceHandler) logA2AReceiveQueued(ctx context.Context, workspaceID,
 		wsName = workspaceID
 	}
 	summary := a2aMethod + " → " + wsName + " (queued for poll)"
-	go func(parent context.Context) {
-		logCtx, cancel := context.WithTimeout(context.WithoutCancel(parent), 30*time.Second)
+	h.goAsync(func() {
+		logCtx, cancel := context.WithTimeout(context.WithoutCancel(ctx), 30*time.Second)
 		defer cancel()
 		LogActivity(logCtx, h.broadcaster, ActivityParams{
 			WorkspaceID:  workspaceID,
@@ -523,7 +523,7 @@ func (h *WorkspaceHandler) logA2AReceiveQueued(ctx context.Context, workspaceID,
 			RequestBody:  json.RawMessage(body),
 			Status:       "ok",
 		})
-	}(ctx)
+	})
 }
 
 // readUsageMap extracts input_tokens / output_tokens from the "usage" key of m.

workspace-server/internal/handlers/a2a_proxy_preflight_test.go

@@ -54,6 +54,7 @@ func TestPreflight_ContainerRunning_ReturnsNil(t *testing.T) {
 	_ = setupTestDB(t)
 	stub := &preflightLocalProv{running: true, err: nil}
 	h := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, h)
 	h.provisioner = stub
 
 	if err := h.preflightContainerHealth(context.Background(), "ws-running-123"); err != nil {
@@ -186,8 +187,8 @@ func TestProxyA2A_Preflight_RoutesThroughProvisionerSSOT(t *testing.T) {
 	}
 
 	var (
-		callsIsRunning             bool
-		callsContainerInspectRaw   bool
+		callsIsRunning                  bool
+		callsContainerInspectRaw        bool
 		callsRunningContainerNameDirect bool
 	)
 	ast.Inspect(fn.Body, func(n ast.Node) bool {

workspace-server/internal/handlers/a2a_proxy_test.go

@@ -262,6 +262,7 @@ func TestProxyA2A_Upstream502_TriggersContainerDeadCheck(t *testing.T) {
 	allowLoopbackForTest(t)
 	broadcaster := newTestBroadcaster()
 	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, handler)
 	cp := &fakeCPProv{running: false}
 	handler.SetCPProvisioner(cp)
 
@@ -324,6 +325,7 @@ func TestProxyA2A_Upstream502_AliveAgent_PropagatesAsIs(t *testing.T) {
 	allowLoopbackForTest(t)
 	broadcaster := newTestBroadcaster()
 	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, handler)
 	cp := &fakeCPProv{running: true}
 	handler.SetCPProvisioner(cp)
 
@@ -513,6 +515,7 @@ func TestProxyA2A_AllowedSelf_SkipsAccessCheck(t *testing.T) {
 	allowLoopbackForTest(t)
 	broadcaster := newTestBroadcaster()
 	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, handler)
 
 	agentServer := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 		w.Header().Set("Content-Type", "application/json")
@@ -661,18 +664,18 @@ func TestProxyA2A_CallerIDDerivedFromBearer(t *testing.T) {
 	//    (column order: workspace_id, activity_type, source_id, target_id, ...)
 	mock.ExpectExec("INSERT INTO activity_logs").
 		WithArgs(
-			"ws-target",                       // $1 workspace_id
-			"a2a_receive",                     // $2 activity_type
-			sqlmock.AnyArg(),                  // $3 source_id — *string("ws-caller"), checked below
-			sqlmock.AnyArg(),                  // $4 target_id
-			sqlmock.AnyArg(),                  // $5 method
-			sqlmock.AnyArg(),                  // $6 summary
-			sqlmock.AnyArg(),                  // $7 request_body
-			sqlmock.AnyArg(),                  // $8 response_body
-			sqlmock.AnyArg(),                  // $9 tool_trace
-			sqlmock.AnyArg(),                  // $10 duration_ms
-			sqlmock.AnyArg(),                  // $11 status
-			sqlmock.AnyArg(),                  // $12 error_detail
+			"ws-target",      // $1 workspace_id
+			"a2a_receive",    // $2 activity_type
+			sqlmock.AnyArg(), // $3 source_id — *string("ws-caller"), checked below
+			sqlmock.AnyArg(), // $4 target_id
+			sqlmock.AnyArg(), // $5 method
+			sqlmock.AnyArg(), // $6 summary
+			sqlmock.AnyArg(), // $7 request_body
+			sqlmock.AnyArg(), // $8 response_body
+			sqlmock.AnyArg(), // $9 tool_trace
+			sqlmock.AnyArg(), // $10 duration_ms
+			sqlmock.AnyArg(), // $11 status
+			sqlmock.AnyArg(), // $12 error_detail
 		).
 		WillReturnResult(sqlmock.NewResult(0, 1))
 
@@ -1716,7 +1719,6 @@ func TestDispatchA2A_RejectsUnsafeURL(t *testing.T) {
 	}
 }
 
-
 // --- handleA2ADispatchError ---
 
 func TestHandleA2ADispatchError_ContextDeadline(t *testing.T) {
@@ -1803,6 +1805,7 @@ func TestMaybeMarkContainerDead_CPOnly_NotRunning(t *testing.T) {
 	mock := setupTestDB(t)
 	setupTestRedis(t)
 	handler := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, handler)
 	cp := &fakeCPProv{running: false}
 	handler.SetCPProvisioner(cp)
 
@@ -1955,6 +1958,7 @@ func TestLogA2AFailure_Smoke(t *testing.T) {
 	mock := setupTestDB(t)
 	setupTestRedis(t)
 	handler := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, handler)
 
 	// Sync workspace-name lookup (called in the caller goroutine).
 	mock.ExpectQuery(`SELECT name FROM workspaces WHERE id =`).
@@ -1973,6 +1977,7 @@ func TestLogA2AFailure_EmptyNameFallback(t *testing.T) {
 	mock := setupTestDB(t)
 	setupTestRedis(t)
 	handler := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, handler)
 
 	// Empty name from DB → summary uses the workspaceID as the name.
 	mock.ExpectQuery(`SELECT name FROM workspaces WHERE id =`).
@@ -1989,6 +1994,7 @@ func TestLogA2ASuccess_Smoke(t *testing.T) {
 	mock := setupTestDB(t)
 	setupTestRedis(t)
 	handler := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, handler)
 
 	mock.ExpectQuery(`SELECT name FROM workspaces WHERE id =`).
 		WithArgs("ws-ok").
@@ -2005,6 +2011,7 @@ func TestLogA2ASuccess_ErrorStatus(t *testing.T) {
 	mock := setupTestDB(t)
 	setupTestRedis(t)
 	handler := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, handler)
 
 	mock.ExpectQuery(`SELECT name FROM workspaces WHERE id =`).
 		WithArgs("ws-err").

workspace-server/internal/handlers/a2a_queue_test.go

@@ -26,6 +26,10 @@ import (
 // setupTestDBForQueueTests creates a sqlmock DB using QueryMatcherEqual (exact
 // string matching) so that ExpectQuery/ExpectExec patterns are compared verbatim.
 // Uses the same global db.DB as setupTestDB so the handler can use it.
+//
+// IMPORTANT: db.DB is saved before assignment and restored via t.Cleanup so
+// that tests running after this one are not polluted by a closed mock.
+// Same fix as setupTestDB (handlers_test.go); same root cause as mc#975.
 func setupTestDBForQueueTests(t *testing.T) sqlmock.Sqlmock {
 	t.Helper()
 	mockDB, mock, err := sqlmock.New(sqlmock.QueryMatcherOption(sqlmock.QueryMatcherEqual))

workspace-server/internal/handlers/delegation.go

@@ -2,6 +2,7 @@ package handlers
 
 import (
 	"context"
+	"database/sql"
 	"encoding/json"
 	"log"
 	"net/http"
@@ -698,7 +699,8 @@ func (h *DelegationHandler) listDelegationsFromLedger(ctx context.Context, works
 
 	var result []map[string]interface{}
 	for rows.Next() {
-		var delegationID, callerID, calleeID, taskPreview, status, resultPreview, errorDetail string
+		var delegationID, callerID, calleeID, taskPreview, status string
+		var resultPreview, errorDetail sql.NullString
 		var lastHeartbeat, deadline, createdAt, updatedAt *time.Time
 		if err := rows.Scan(
 			&delegationID, &callerID, &calleeID, &taskPreview,
@@ -717,11 +719,11 @@ func (h *DelegationHandler) listDelegationsFromLedger(ctx context.Context, works
 			"updated_at":    updatedAt,
 			"_ledger":       true, // marker so callers know this row is from the ledger
 		}
-		if resultPreview != "" {
-			entry["response_preview"] = textutil.TruncateBytes(resultPreview, 300)
+		if resultPreview.Valid && resultPreview.String != "" {
+			entry["response_preview"] = textutil.TruncateBytes(resultPreview.String, 300)
 		}
-		if errorDetail != "" {
-			entry["error"] = errorDetail
+		if errorDetail.Valid && errorDetail.String != "" {
+			entry["error"] = errorDetail.String
 		}
 		if lastHeartbeat != nil {
 			entry["last_heartbeat"] = lastHeartbeat

workspace-server/internal/handlers/delegation_list_test.go

@@ -145,6 +145,54 @@ func TestListDelegationsFromLedger_MultipleRows(t *testing.T) {
 	}
 }
 
+func TestListDelegationsFromLedger_NullsOmitted(t *testing.T) {
+	// last_heartbeat, deadline, result_preview, error_detail are all NULL.
+	// Handler must not panic and must omit those keys from the map.
+	mockDB, mock, err := sqlmock.New()
+	if err != nil {
+		t.Fatalf("failed to create sqlmock: %v", err)
+	}
+	prevDB := db.DB
+	db.DB = mockDB
+	t.Cleanup(func() { mockDB.Close(); db.DB = prevDB })
+
+	now := time.Now()
+	rows := sqlmock.NewRows([]string{
+		"delegation_id", "caller_id", "callee_id", "task_preview",
+		"status", "result_preview", "error_detail",
+		"last_heartbeat", "deadline", "created_at", "updated_at",
+	}).
+		AddRow("del-1", "ws-1", "ws-2", "task", "queued", nil, nil, nil, nil, now, now)
+	mock.ExpectQuery("SELECT .+ FROM delegations").
+		WithArgs("ws-1").
+		WillReturnRows(rows)
+
+	broadcaster := newTestBroadcaster()
+	wh := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", t.TempDir())
+	dh := NewDelegationHandler(wh, broadcaster)
+
+	got := dh.listDelegationsFromLedger(context.Background(), "ws-1")
+	if len(got) != 1 {
+		t.Fatalf("expected 1 entry, got %d", len(got))
+	}
+	e := got[0]
+	if _, ok := e["last_heartbeat"]; ok {
+		t.Error("last_heartbeat should be absent when NULL")
+	}
+	if _, ok := e["deadline"]; ok {
+		t.Error("deadline should be absent when NULL")
+	}
+	if _, ok := e["response_preview"]; ok {
+		t.Error("response_preview should be absent when NULL result_preview")
+	}
+	if _, ok := e["error"]; ok {
+		t.Error("error should be absent when NULL error_detail")
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("sqlmock expectations: %v", err)
+	}
+}
+
 func TestListDelegationsFromLedger_QueryError(t *testing.T) {
 	// Query failure returns nil — graceful fallback, no panic.
 	mockDB, mock, err := sqlmock.New()

workspace-server/internal/handlers/external_connection.go

@@ -646,8 +646,12 @@ const externalOpenClawTemplate = `# OpenClaw MCP config — outbound tool path.
 # external machine today, pair with the Python SDK tab.
 
 # 1. Install openclaw CLI + the workspace runtime wheel:
+#    The version pin (>=0.1.999) ensures the "molecule-mcp" console
+#    script is present — it is what keeps the workspace ALIVE on canvas
+#    (register-on-startup + 20s heartbeat). Older versions only ship
+#    a2a_mcp_server which does not heartbeat.
 npm install -g openclaw@latest
-pip install molecule-ai-workspace-runtime
+pip install "molecule-ai-workspace-runtime>=0.1.999"
 
 # 2. Onboard openclaw against your model provider (one-time setup).
 #    --non-interactive needs an explicit --provider + --model so it

workspace-server/internal/handlers/handlers_test.go

@@ -29,6 +29,11 @@ func init() {
 // setupTestDB creates a sqlmock DB and assigns it to the global db.DB.
 // It also disables the SSRF URL check so that httptest.NewServer loopback
 // URLs and fake hostnames (*.example) used in tests don't trigger rejections.
+//
+// IMPORTANT: db.DB is saved before assignment and restored via t.Cleanup so
+// that tests running after this one are not polluted by a closed mock.
+// This is the single root cause of the systemic CI/Platform (Go) failures on
+// main HEAD 8026f020 (mc#975).
 func setupTestDB(t *testing.T) sqlmock.Sqlmock {
 	t.Helper()
 	mockDB, mock, err := sqlmock.New()
@@ -57,6 +62,11 @@ func setupTestDB(t *testing.T) sqlmock.Sqlmock {
 	return mock
 }
 
+func waitForHandlerAsyncBeforeDBCleanup(t *testing.T, h *WorkspaceHandler) {
+	t.Helper()
+	t.Cleanup(h.waitAsyncForTest)
+}
+
 // setupTestRedis creates a miniredis instance and assigns it to the global db.RDB.
 func setupTestRedis(t *testing.T) *miniredis.Miniredis {
 	t.Helper()
@@ -356,6 +366,11 @@ func TestWorkspaceCreate(t *testing.T) {
 }
 
 func TestBuildProvisionerConfig_IncludesAwarenessSettings(t *testing.T) {
+	mock := setupTestDB(t)
+	mock.ExpectQuery(`SELECT digest FROM runtime_image_pins`).
+		WithArgs("claude-code").
+		WillReturnError(sql.ErrNoRows)
+
 	broadcaster := newTestBroadcaster()
 	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", "/tmp/configs")
 

workspace-server/internal/handlers/instructions_test.go

@@ -2,10 +2,12 @@ package handlers
 
 import (
 	"bytes"
+	"context"
 	"encoding/json"
 	"errors"
 	"net/http"
 	"net/http/httptest"
+	"regexp"
 	"testing"
 	"time"
 
@@ -80,117 +82,135 @@ func TestInstructionsList_ByWorkspaceID(t *testing.T) {
 	if w.Code != http.StatusOK {
 		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
 	}
-	var out []Instruction
-	if err := json.Unmarshal(w.Body.Bytes(), &out); err != nil {
-		t.Fatalf("response not valid JSON: %v", err)
+	var result []Instruction
+	if err := json.Unmarshal(w.Body.Bytes(), &result); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
 	}
-	if len(out) != 2 {
-		t.Errorf("expected 2 instructions, got %d", len(out))
+	if len(result) != 2 {
+		t.Fatalf("expected 2 instructions, got %d", len(result))
 	}
-	if out[0].Scope != "global" {
-		t.Errorf("first row scope: expected global, got %s", out[0].Scope)
+	if result[0].Scope != "global" || result[1].Scope != "workspace" {
+		t.Fatalf("expected global then workspace instructions, got %#v", result)
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
-		t.Errorf("unmet expectations: %v", err)
+		t.Fatalf("unmet expectations: %v", err)
 	}
 }
 
-func TestInstructionsList_ByScope(t *testing.T) {
+func TestInstructionsHandler_List_WithScopeFilter(t *testing.T) {
 	mock := setupTestDB(t)
-	h := NewInstructionsHandler()
+	handler := NewInstructionsHandler()
 
-	w, c := newGetRequest("/instructions?scope=global")
-	c.Request = httptest.NewRequest(http.MethodGet, "/instructions?scope=global", nil)
+	rows := sqlmock.NewRows([]string{
+		"id", "scope", "scope_target", "title", "content", "priority", "enabled", "created_at", "updated_at",
+	}).AddRow("inst-1", "global", nil, "Be kind", "Always be kind", 10, true,
+		time.Now(), time.Now())
 
-	rows := sqlmock.NewRows(instructionCols).
-		AddRow("inst-g", "global", nil, "Global Rule", "Follow policy.", 10, true, time.Now(), time.Now())
-	mock.ExpectQuery("SELECT id, scope, scope_target, title, content, priority, enabled, created_at, updated_at FROM platform_instructions WHERE 1=1").
+	mock.ExpectQuery(regexp.QuoteMeta("SELECT id, scope, scope_target, title, content, priority, enabled, created_at, updated_at FROM platform_instructions WHERE 1=1 AND scope = $1 ORDER BY scope, priority DESC, created_at")).
 		WithArgs("global").
 		WillReturnRows(rows)
 
-	h.List(c)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("GET", "/instructions?scope=global", nil)
+
+	handler.List(c)
 
 	if w.Code != http.StatusOK {
-		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+		t.Fatalf("expected 200, got %d", w.Code)
 	}
-	var out []Instruction
-	if err := json.Unmarshal(w.Body.Bytes(), &out); err != nil {
-		t.Fatalf("response not valid JSON: %v", err)
+	var result []Instruction
+	if err := json.Unmarshal(w.Body.Bytes(), &result); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
 	}
-	if len(out) != 1 || out[0].Scope != "global" {
-		t.Errorf("unexpected response: %v", out)
+	if len(result) != 1 {
+		t.Fatalf("expected 1 instruction, got %d", len(result))
+	}
+	if result[0].Scope != "global" {
+		t.Errorf("expected scope 'global', got %q", result[0].Scope)
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
-		t.Errorf("unmet expectations: %v", err)
+		t.Fatalf("unmet expectations: %v", err)
 	}
 }
 
-func TestInstructionsList_AllNoParams(t *testing.T) {
+func TestInstructionsHandler_List_WithWorkspaceID(t *testing.T) {
 	mock := setupTestDB(t)
-	h := NewInstructionsHandler()
+	handler := NewInstructionsHandler()
+	wsID := "ws-test-123"
 
-	w, c := newGetRequest("/instructions")
+	rows := sqlmock.NewRows([]string{
+		"id", "scope", "scope_target", "title", "content", "priority", "enabled", "created_at", "updated_at",
+	}).AddRow("inst-1", "global", nil, "Global rule", "Stay safe", 5, true,
+		time.Now(), time.Now()).
+		AddRow("inst-2", "workspace", &wsID, "WS rule", "Use HTTPS", 10, true,
+			time.Now(), time.Now())
 
-	rows := sqlmock.NewRows(instructionCols)
-	mock.ExpectQuery("SELECT id, scope, scope_target, title, content, priority, enabled, created_at, updated_at FROM platform_instructions WHERE 1=1").
+	mock.ExpectQuery("SELECT id, scope, scope_target, title, content, priority, enabled, created_at, updated_at FROM platform_instructions WHERE enabled = true AND \\(").
+		WithArgs(wsID).
 		WillReturnRows(rows)
 
-	h.List(c)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("GET", "/instructions?workspace_id="+wsID, nil)
+
+	handler.List(c)
 
 	if w.Code != http.StatusOK {
-		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+		t.Fatalf("expected 200, got %d", w.Code)
 	}
-	var out []Instruction
-	if err := json.Unmarshal(w.Body.Bytes(), &out); err != nil {
-		t.Fatalf("response not valid JSON: %v", err)
+	var result []Instruction
+	if err := json.Unmarshal(w.Body.Bytes(), &result); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
 	}
-	// Empty slice, not nil
-	if out == nil {
-		t.Error("expected empty slice, got nil")
+	if len(result) != 2 {
+		t.Fatalf("expected 2 instructions, got %d", len(result))
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
-		t.Errorf("unmet expectations: %v", err)
+		t.Fatalf("unmet expectations: %v", err)
 	}
 }
 
-func TestInstructionsList_DBError(t *testing.T) {
+func TestInstructionsHandler_List_QueryError(t *testing.T) {
 	mock := setupTestDB(t)
-	h := NewInstructionsHandler()
-
-	w, c := newGetRequest("/instructions")
-	c.Request = httptest.NewRequest(http.MethodGet, "/instructions", nil)
+	handler := NewInstructionsHandler()
 
 	mock.ExpectQuery("SELECT id, scope, scope_target, title, content, priority, enabled, created_at, updated_at FROM platform_instructions WHERE 1=1").
-		WillReturnError(errors.New("connection refused"))
+		WillReturnError(context.DeadlineExceeded)
 
-	h.List(c)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("GET", "/instructions", nil)
+
+	handler.List(c)
 
 	if w.Code != http.StatusInternalServerError {
-		t.Fatalf("expected 500, got %d: %s", w.Code, w.Body.String())
-	}
-	if err := mock.ExpectationsWereMet(); err != nil {
-		t.Errorf("unmet expectations: %v", err)
+		t.Fatalf("expected 500, got %d", w.Code)
 	}
 }
 
-// ─── Create ───────────────────────────────────────────────────────────────────
+// ── Create ──────────────────────────────────────────────────────────────────────
 
-func TestInstructionsCreate_ValidGlobal(t *testing.T) {
+func TestInstructionsHandler_Create_Success(t *testing.T) {
 	mock := setupTestDB(t)
-	h := NewInstructionsHandler()
-
-	w, c := newPostRequest("/instructions", map[string]interface{}{
-		"scope":    "global",
-		"title":    "Be Helpful",
-		"content":  "Always be helpful to the user.",
-		"priority": 10,
-	})
+	handler := NewInstructionsHandler()
 
 	mock.ExpectQuery("INSERT INTO platform_instructions").
-		WithArgs("global", nil, "Be Helpful", "Always be helpful to the user.", 10).
-		WillReturnRows(sqlmock.NewRows([]string{"id"}).AddRow("new-inst-1"))
+		WithArgs("global", nil, "Be kind", "Always be kind", 5).
+		WillReturnRows(sqlmock.NewRows([]string{"id"}).AddRow("new-inst-id"))
 
-	h.Create(c)
+	body, _ := json.Marshal(map[string]interface{}{
+		"scope":    "global",
+		"title":    "Be kind",
+		"content":  "Always be kind",
+		"priority": 5,
+	})
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("POST", "/instructions", bytes.NewReader(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Create(c)
 
 	if w.Code != http.StatusCreated {
 		t.Fatalf("expected 201, got %d: %s", w.Code, w.Body.String())
@@ -199,8 +219,8 @@ func TestInstructionsCreate_ValidGlobal(t *testing.T) {
 	if err := json.Unmarshal(w.Body.Bytes(), &out); err != nil {
 		t.Fatalf("response not valid JSON: %v", err)
 	}
-	if out["id"] != "new-inst-1" {
-		t.Errorf("expected id new-inst-1, got %s", out["id"])
+	if out["id"] != "new-inst-id" {
+		t.Errorf("expected id new-inst-id, got %s", out["id"])
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
 		t.Errorf("unmet expectations: %v", err)
@@ -299,56 +319,65 @@ func TestInstructionsCreate_InvalidScope(t *testing.T) {
 	}
 }
 
-func TestInstructionsCreate_WorkspaceScopeNoTarget(t *testing.T) {
+func TestInstructionsHandler_Create_WorkspaceScopeMissingScopeTarget(t *testing.T) {
 	setupTestDB(t)
-	h := NewInstructionsHandler()
+	handler := NewInstructionsHandler()
 
-	w, c := newPostRequest("/instructions", map[string]interface{}{
+	body, _ := json.Marshal(map[string]interface{}{
 		"scope":   "workspace",
-		"title":   "Missing Target",
-		"content": "Workspace scope without scope_target.",
+		"title":   "Test",
+		"content": "Test content",
 	})
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("POST", "/instructions", bytes.NewReader(body))
+	c.Request.Header.Set("Content-Type", "application/json")
 
-	h.Create(c)
+	handler.Create(c)
 
 	if w.Code != http.StatusBadRequest {
 		t.Fatalf("expected 400, got %d: %s", w.Code, w.Body.String())
 	}
 }
 
-func TestInstructionsCreate_ContentTooLong(t *testing.T) {
+func TestInstructionsHandler_Create_ContentTooLong(t *testing.T) {
 	setupTestDB(t)
-	h := NewInstructionsHandler()
+	handler := NewInstructionsHandler()
 
-	// Build a string longer than maxInstructionContentLen (8192).
-	longContent := string(make([]byte, maxInstructionContentLen+1))
-
-	w, c := newPostRequest("/instructions", map[string]interface{}{
+	longContent := string(bytes.Repeat([]byte("x"), 8193))
+	body, _ := json.Marshal(map[string]interface{}{
 		"scope":   "global",
-		"title":   "Too Long",
+		"title":   "Test",
 		"content": longContent,
 	})
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("POST", "/instructions", bytes.NewReader(body))
+	c.Request.Header.Set("Content-Type", "application/json")
 
-	h.Create(c)
+	handler.Create(c)
 
 	if w.Code != http.StatusBadRequest {
 		t.Fatalf("expected 400, got %d: %s", w.Code, w.Body.String())
 	}
 }
 
-func TestInstructionsCreate_TitleTooLong(t *testing.T) {
+func TestInstructionsHandler_Create_TitleTooLong(t *testing.T) {
 	setupTestDB(t)
-	h := NewInstructionsHandler()
+	handler := NewInstructionsHandler()
 
-	longTitle := string(make([]byte, 201))
-
-	w, c := newPostRequest("/instructions", map[string]interface{}{
+	longTitle := string(bytes.Repeat([]byte("x"), 201))
+	body, _ := json.Marshal(map[string]interface{}{
 		"scope":   "global",
 		"title":   longTitle,
-		"content": "Short content.",
+		"content": "Short content",
 	})
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("POST", "/instructions", bytes.NewReader(body))
+	c.Request.Header.Set("Content-Type", "application/json")
 
-	h.Create(c)
+	handler.Create(c)
 
 	if w.Code != http.StatusBadRequest {
 		t.Fatalf("expected 400, got %d: %s", w.Code, w.Body.String())
@@ -842,43 +871,250 @@ func TestInstructionsResolve_ScopeTransitionOnlyGlobal(t *testing.T) {
 	if w.Code != http.StatusOK {
 		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
 	}
-	var out struct {
-		Instructions string `json:"instructions"`
-	}
-	if err := json.Unmarshal(w.Body.Bytes(), &out); err != nil {
-		t.Fatalf("response not valid JSON: %v", err)
-	}
-	// Two global instructions share one section header.
-	if bytes.Count([]byte(out.Instructions), []byte("Platform-Wide Rules")) != 1 {
-		t.Error("expect exactly one 'Platform-Wide Rules' header for consecutive global rows")
-	}
 	if err := mock.ExpectationsWereMet(); err != nil {
-		t.Errorf("unmet expectations: %v", err)
+		t.Fatalf("unmet expectations: %v", err)
 	}
 }
 
-// ─── Update: empty body (all nil — no-op update) ─────────────────────────────
-
-func TestInstructionsUpdate_EmptyBody(t *testing.T) {
+func TestInstructionsHandler_Update_NotFound(t *testing.T) {
 	mock := setupTestDB(t)
-	h := NewInstructionsHandler()
+	handler := NewInstructionsHandler()
 
-	instID := "inst-empty-update"
-	w, c := newPutRequest("/instructions/"+instID, map[string]interface{}{})
-	c.Params = []gin.Param{{Key: "id", Value: instID}}
+	mock.ExpectExec(regexp.QuoteMeta("UPDATE platform_instructions SET\n\t\t\t\ttitle = COALESCE($2, title),\n\t\t\t\tcontent = COALESCE($3, content),\n\t\t\t\tpriority = COALESCE($4, priority),\n\t\t\t\tenabled = COALESCE($5, enabled),\n\t\t\t\tupdated_at = NOW()\n\t\t\t\tWHERE id = $1")).
+		WithArgs("nonexistent", sqlmock.AnyArg(), nil, nil, nil).
+		WillReturnResult(sqlmock.NewResult(0, 0))
 
-	// COALESCE(nil, ...) = unchanged; still updates updated_at.
-	// Args order: ($1=id, $2=title, $3=content, $4=priority, $5=enabled)
-	mock.ExpectExec("UPDATE platform_instructions SET").
-		WithArgs(instID, sqlmock.AnyArg(), sqlmock.AnyArg(), sqlmock.AnyArg(), sqlmock.AnyArg()).
+	body, _ := json.Marshal(map[string]interface{}{"title": "Updated title"})
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "nonexistent"}}
+	c.Request = httptest.NewRequest("PUT", "/instructions/nonexistent", bytes.NewReader(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Update(c)
+
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatalf("unmet expectations: %v", err)
+	}
+}
+
+func TestInstructionsHandler_Update_ContentTooLong(t *testing.T) {
+	setupTestDB(t)
+	handler := NewInstructionsHandler()
+
+	longContent := string(bytes.Repeat([]byte("x"), 8193))
+	body, _ := json.Marshal(map[string]interface{}{"content": longContent})
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "inst-1"}}
+	c.Request = httptest.NewRequest("PUT", "/instructions/inst-1", bytes.NewReader(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Update(c)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestInstructionsHandler_Update_TitleTooLong(t *testing.T) {
+	setupTestDB(t)
+	handler := NewInstructionsHandler()
+
+	longTitle := string(bytes.Repeat([]byte("x"), 201))
+	body, _ := json.Marshal(map[string]interface{}{"title": longTitle})
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "inst-1"}}
+	c.Request = httptest.NewRequest("PUT", "/instructions/inst-1", bytes.NewReader(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Update(c)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+// ── Delete ─────────────────────────────────────────────────────────────────────
+
+func TestInstructionsHandler_Delete_Success(t *testing.T) {
+	mock := setupTestDB(t)
+	handler := NewInstructionsHandler()
+
+	mock.ExpectExec(regexp.QuoteMeta("DELETE FROM platform_instructions WHERE id = $1")).
+		WithArgs("inst-1").
 		WillReturnResult(sqlmock.NewResult(0, 1))
 
-	h.Update(c)
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "inst-1"}}
+	c.Request = httptest.NewRequest("DELETE", "/instructions/inst-1", nil)
+
+	handler.Delete(c)
 
 	if w.Code != http.StatusOK {
-		t.Fatalf("expected 200 for empty body, got %d: %s", w.Code, w.Body.String())
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
 	}
 	if err := mock.ExpectationsWereMet(); err != nil {
-		t.Errorf("unmet expectations: %v", err)
+		t.Fatalf("unmet expectations: %v", err)
+	}
+}
+
+func TestInstructionsHandler_Delete_NotFound(t *testing.T) {
+	mock := setupTestDB(t)
+	handler := NewInstructionsHandler()
+
+	mock.ExpectExec(regexp.QuoteMeta("DELETE FROM platform_instructions WHERE id = $1")).
+		WithArgs("nonexistent").
+		WillReturnResult(sqlmock.NewResult(0, 0))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "nonexistent"}}
+	c.Request = httptest.NewRequest("DELETE", "/instructions/nonexistent", nil)
+
+	handler.Delete(c)
+
+	if w.Code != http.StatusNotFound {
+		t.Fatalf("expected 404, got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatalf("unmet expectations: %v", err)
+	}
+}
+
+// ── Resolve ────────────────────────────────────────────────────────────────────
+
+func TestInstructionsHandler_Resolve_Empty(t *testing.T) {
+	mock := setupTestDB(t)
+	handler := NewInstructionsHandler()
+	wsID := "ws-resolve-1"
+
+	mock.ExpectQuery("SELECT scope, title, content FROM platform_instructions WHERE enabled = true AND").
+		WithArgs(wsID).
+		WillReturnRows(sqlmock.NewRows([]string{"scope", "title", "content"}))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: wsID}}
+	c.Request = httptest.NewRequest("GET", "/workspaces/"+wsID+"/instructions/resolve", nil)
+
+	handler.Resolve(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+	var resp map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
+	}
+	if resp["workspace_id"] != wsID {
+		t.Errorf("expected workspace_id %q, got %v", wsID, resp["workspace_id"])
+	}
+	if resp["instructions"] != "" {
+		t.Errorf("expected empty instructions, got %q", resp["instructions"])
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatalf("unmet expectations: %v", err)
+	}
+}
+
+func TestInstructionsHandler_Resolve_WithInstructions(t *testing.T) {
+	mock := setupTestDB(t)
+	handler := NewInstructionsHandler()
+	wsID := "ws-resolve-2"
+
+	rows := sqlmock.NewRows([]string{"scope", "title", "content"}).
+		AddRow("global", "Be safe", "No SSRF").
+		AddRow("workspace", "WS Rule", "Use HTTPS")
+
+	mock.ExpectQuery("SELECT scope, title, content FROM platform_instructions WHERE enabled = true AND").
+		WithArgs(wsID).
+		WillReturnRows(rows)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: wsID}}
+	c.Request = httptest.NewRequest("GET", "/workspaces/"+wsID+"/instructions/resolve", nil)
+
+	handler.Resolve(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+	var resp map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
+	}
+	instructions, ok := resp["instructions"].(string)
+	if !ok {
+		t.Fatalf("instructions field is not a string: %T", resp["instructions"])
+	}
+	if instructions == "" {
+		t.Fatalf("expected non-empty instructions")
+	}
+	// Verify scope headers are present
+	if !bytes.Contains([]byte(instructions), []byte("Platform-Wide Rules")) {
+		t.Errorf("expected 'Platform-Wide Rules' header in instructions")
+	}
+	if !bytes.Contains([]byte(instructions), []byte("Role-Specific Rules")) {
+		t.Errorf("expected 'Role-Specific Rules' header in instructions")
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Fatalf("unmet expectations: %v", err)
+	}
+}
+
+func TestInstructionsHandler_Resolve_MissingWorkspaceID(t *testing.T) {
+	setupTestDB(t)
+	handler := NewInstructionsHandler()
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: ""}}
+	c.Request = httptest.NewRequest("GET", "/workspaces//instructions/resolve", nil)
+
+	handler.Resolve(c)
+
+	if w.Code != http.StatusBadRequest {
+		t.Fatalf("expected 400, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+// scanInstructions is called by the List handler — verify it handles
+// rows.Err() gracefully without panicking.
+func TestInstructionsHandler_List_ScanErrorContinues(t *testing.T) {
+	mock := setupTestDB(t)
+	handler := NewInstructionsHandler()
+
+	rows := sqlmock.NewRows([]string{
+		"id", "scope", "scope_target", "title", "content", "priority", "enabled", "created_at", "updated_at",
+	}).AddRow("inst-1", "global", nil, "Good", "Content here", 5, true, time.Now(), time.Now()).
+		RowError(1, context.DeadlineExceeded) // error on row 2 (if it existed)
+
+	mock.ExpectQuery("SELECT id, scope, scope_target, title, content, priority, enabled, created_at, updated_at FROM platform_instructions WHERE 1=1").
+		WillReturnRows(rows)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Request = httptest.NewRequest("GET", "/instructions", nil)
+
+	handler.List(c)
+
+	// Should still return 200 and the one valid row
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d", w.Code)
+	}
+	var result []Instruction
+	if err := json.Unmarshal(w.Body.Bytes(), &result); err != nil {
+		t.Fatalf("invalid JSON: %v", err)
+	}
+	// The valid row should still be returned (error is logged, not fatal)
+	if len(result) != 1 {
+		t.Fatalf("expected 1 instruction despite row error, got %d", len(result))
 	}
 }

workspace-server/internal/handlers/org_helpers.go

@@ -15,6 +15,7 @@ import (
 
 	"gopkg.in/yaml.v3"
 )
+
 // resolvePromptRef reads a prompt body from either an inline string or a
 // file ref relative to the workspace's files_dir. Inline always wins when
 // both are non-empty (caller-provided inline is more authoritative than a

workspace-server/internal/handlers/org_helpers_pure_test.go

@@ -104,8 +104,8 @@ func TestHasUnresolvedVarRef_Resolved(t *testing.T) {
 		// documents this design choice; callers who need empty=resolved should
 		// pre-process the output before calling hasUnresolvedVarRef.
 		{"${VAR}", "", true},
-		{"${VAR}", "value", false},                    // var replaced
-		{"$VAR", "value", false},                      // bare var replaced
+		{"${VAR}", "value", false}, // var replaced
+		{"$VAR", "value", false},   // bare var replaced
 		{"prefix${VAR}suffix", "prefixvaluesuffix", false},
 		{"${A}${B}", "ab", false},
 		// FOO=FOO and BAR=BAR — both vars found and replaced. Expanded output
@@ -125,14 +125,14 @@ func TestHasUnresolvedVarRef_Resolved(t *testing.T) {
 func TestHasUnresolvedVarRef_Unresolved(t *testing.T) {
 	// Expansion left the refs intact → unresolved.
 	cases := []struct {
-		orig    string
+		orig     string
 		expanded string
 	}{
-		{"${VAR}", "${VAR}"},       // untouched
-		{"$VAR", "$VAR"},           // bare untouched
+		{"${VAR}", "${VAR}"}, // untouched
+		{"$VAR", "$VAR"},     // bare untouched
 		{"prefix${VAR}suffix", "prefix${VAR}suffix"},
-		{"${A}${B}", "${A}${B}"},   // both unresolved
-		{"${FOO}", ""},             // empty result with var ref in original
+		{"${A}${B}", "${A}${B}"}, // both unresolved
+		{"${FOO}", ""},           // empty result with var ref in original
 	}
 	for _, tc := range cases {
 		t.Run(tc.orig, func(t *testing.T) {
@@ -205,8 +205,8 @@ func TestMergeCategoryRouting_WorkspaceOverrides(t *testing.T) {
 		"ui":       {"Frontend Engineer"},
 	}
 	ws := map[string][]string{
-		"security": {"SRE Team"}, // narrows
-		"ui":       {},           // drops
+		"security": {"SRE Team"},      // narrows
+		"ui":       {},                // drops
 		"infra":    {"Platform Team"}, // adds
 	}
 	r := mergeCategoryRouting(defaults, ws)
@@ -467,6 +467,44 @@ func TestExpandWithEnv_PartiallyPresent(t *testing.T) {
 	assert.Equal(t, "yes and ${NOT_SET}", result)
 }
 
+func TestExpandWithEnv_EmbeddedMissingProcessEnvStaysLiteral(t *testing.T) {
+	t.Setenv("MOL_TEST_EMBEDDED_MISSING", "")
+
+	result := expandWithEnv("prefix/${MOL_TEST_EMBEDDED_MISSING}/suffix", map[string]string{})
+	assert.Equal(t, "prefix/${MOL_TEST_EMBEDDED_MISSING}/suffix", result)
+}
+
+// POSIX identifier guard regression tests (CWE-78 fix).
+// Keys not starting with [a-zA-Z_] must not be looked up in env or os.Getenv.
+func TestExpandWithEnv_DigitPrefix_NotExpanded(t *testing.T) {
+	// ${0}, ${5}, ${1VAR} — numeric prefix → not a valid shell identifier.
+	// Guard must return "$0", "$5", "$1VAR" literally; no env lookup.
+	cases := []struct {
+		input string
+		want  string
+	}{
+		{"${0}", "$0"},
+		{"${5}", "$5"},
+		{"${1VAR}", "$1VAR"},
+		{"prefix ${0} suffix", "prefix $0 suffix"},
+		{"$0", "$0"},
+		{"$5", "$5"},
+		{"HOME=${HOME}", "HOME=${HOME}"}, // HOME is valid but embedded in larger string
+	}
+	for _, tc := range cases {
+		t.Run(tc.input, func(t *testing.T) {
+			got := expandWithEnv(tc.input, map[string]string{})
+			assert.Equal(t, tc.want, got)
+		})
+	}
+}
+
+func TestExpandWithEnv_EmptyKey_ReturnsDollar(t *testing.T) {
+	// ${} → "$" (empty key, guard returns "$")
+	result := expandWithEnv("value=${}", map[string]string{})
+	assert.Equal(t, "value=$", result)
+}
+
 // mergeCategoryRouting tests — unions defaults with per-workspace routing.
 
 // ── Additional coverage: mergeCategoryRouting ──────────────────────
@@ -546,8 +584,8 @@ func TestRenderCategoryRoutingYAML_SingleCategory(t *testing.T) {
 
 func TestRenderCategoryRoutingYAML_MultipleCategoriesSorted(t *testing.T) {
 	routing := map[string][]string{
-		"zebra":   {"RoleZ"},
-		"alpha":   {"RoleA"},
+		"zebra":      {"RoleZ"},
+		"alpha":      {"RoleA"},
 		"middleware": {"RoleM"},
 	}
 	result, err := renderCategoryRoutingYAML(routing)

workspace-server/internal/handlers/plugins_install_eic_test.go

@@ -342,6 +342,11 @@ func TestPluginInstall_InstanceLookupError_Returns503(t *testing.T) {
 // ---------- dispatch: uninstall ----------
 
 func TestPluginUninstall_SaaS_DispatchesToEIC(t *testing.T) {
+	mock := setupTestDB(t)
+	mock.ExpectExec("DELETE FROM workspace_plugins WHERE workspace_id").
+		WithArgs("ws-1", "browser-automation").
+		WillReturnResult(sqlmock.NewResult(0, 1))
+
 	stubReadPluginManifestViaEIC(t, func(ctx context.Context, instanceID, runtime, pluginName string) ([]byte, error) {
 		return []byte("name: browser-automation\nskills:\n  - browse\n"), nil
 	})

workspace-server/internal/handlers/plugins_test.go

@@ -629,6 +629,9 @@ func TestPluginInstall_RejectsUnknownScheme(t *testing.T) {
 }
 
 func TestPluginInstall_LocalSourceReachesContainerLookup(t *testing.T) {
+	mock := setupTestDB(t)
+	expectAllowlistAllowAll(mock)
+
 	base := t.TempDir()
 	pluginDir := filepath.Join(base, "demo")
 	_ = os.MkdirAll(pluginDir, 0o755)
@@ -955,14 +958,14 @@ func TestLogInstallLimitsOnce(t *testing.T) {
 
 func TestRegexpEscapeForAwk(t *testing.T) {
 	cases := map[string]string{
-		"my-plugin":                 `my-plugin`,
-		"# Plugin: foo /":           `# Plugin: foo \/`,
-		"# Plugin: a.b /":           `# Plugin: a\.b \/`,
-		"foo[bar]":                  `foo\[bar\]`,
-		"a*b+c?":                    `a\*b\+c\?`,
-		"path|with|pipes":           `path\|with\|pipes`,
-		`back\slash`:                `back\\slash`,
-		"":                          ``,
+		"my-plugin":       `my-plugin`,
+		"# Plugin: foo /": `# Plugin: foo \/`,
+		"# Plugin: a.b /": `# Plugin: a\.b \/`,
+		"foo[bar]":        `foo\[bar\]`,
+		"a*b+c?":          `a\*b\+c\?`,
+		"path|with|pipes": `path\|with\|pipes`,
+		`back\slash`:      `back\\slash`,
+		"":                ``,
 	}
 	for in, want := range cases {
 		got := regexpEscapeForAwk(in)
@@ -1247,7 +1250,7 @@ func TestPluginDownload_GithubSchemeStreamsTarball(t *testing.T) {
 		scheme: "github",
 		fetchFn: func(_ context.Context, _ string, dst string) (string, error) {
 			files := map[string]string{
-				"plugin.yaml":            "name: remote-plugin\nversion: 1.0.0\n",
+				"plugin.yaml":             "name: remote-plugin\nversion: 1.0.0\n",
 				"skills/x/SKILL.md":       "---\nname: x\n---\n",
 				"adapters/claude_code.py": "from plugins_registry.builtins import AgentskillsAdaptor as Adaptor\n",
 			}

workspace-server/internal/handlers/restart_signals.go

@@ -58,7 +58,7 @@ func (h *WorkspaceHandler) gracefulPreRestart(ctx context.Context, workspaceID s
 	// Non-blocking send — don't stall the restart cycle.
 	// Run in a detached goroutine so the caller (runRestartCycle) can
 	// proceed to stopForRestart without waiting.
-	go func() {
+	h.goAsync(func() {
 		signalCtx, cancel := context.WithTimeout(context.Background(), restartSignalTimeout)
 		defer cancel()
 
@@ -109,7 +109,7 @@ func (h *WorkspaceHandler) gracefulPreRestart(ctx context.Context, workspaceID s
 		} else {
 			log.Printf("A2AGracefulRestart: %s returned status %d — proceeding with stop", workspaceID, resp.StatusCode)
 		}
-	}()
+	})
 }
 
 // resolveAgentURLForRestartSignal returns the routable URL for the workspace

workspace-server/internal/handlers/restart_signals_test.go

@@ -271,6 +271,7 @@ func TestGracefulPreRestart_URLResolutionError(t *testing.T) {
 		WorkspaceHandler: newHandlerWithTestDeps(t),
 		errToReturn:      context.DeadlineExceeded,
 	}
+	waitForHandlerAsyncBeforeDBCleanup(t, hWrapper.WorkspaceHandler)
 
 	hWrapper.gracefulPreRestart(context.Background(), "ws-url-err-111")
 	time.Sleep(200 * time.Millisecond)

workspace-server/internal/handlers/template_files_agent_home_stub_test.go

@@ -0,0 +1,117 @@
+package handlers
+
+// template_files_agent_home_stub_test.go — pins the Phase-1 stub
+// contract for the /agent-home root added by internal#425 RFC.
+//
+// Today (pre-Phase-2b), every Files API verb against `?root=/agent-home`
+// must return HTTP 501 with the canonical pending-message body. The
+// stub MUST NOT:
+//   1. Hit the DB (the workspace might not even exist yet from the
+//      canvas's POV — the root selector is testable without one).
+//   2. Touch the EIC tunnel / Docker / template-dir paths — those
+//      would 500/404/[] depending on the env and confuse the canvas.
+//   3. Accept writes/deletes that the future docker-exec backend
+//      would reject — fail closed.
+//
+// When Phase 2b lands, this file gets replaced by a real
+// docker-exec dispatch test; the stub-message constant in
+// templates.go disappears.
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+// TestAgentHomeAllowedRoot pins that /agent-home is in the allowedRoots
+// set. Without this, a future refactor that drops the key would
+// silently degrade the canvas root selector to a 400 instead of the
+// stub 501.
+func TestAgentHomeAllowedRoot(t *testing.T) {
+	if !allowedRoots["/agent-home"] {
+		t.Fatal("/agent-home must be in allowedRoots — RFC #425 contract")
+	}
+}
+
+// TestAgentHomeStub_AllVerbs_Return501 pins the canonical stub
+// response across all four verbs. Each must:
+//
+//   - status 501
+//   - body contains the canonical "/agent-home not implemented" prefix
+//   - NOT contain "workspace not found" (proves we short-circuit before
+//     the DB lookup)
+//
+// Driven as a table to keep symmetry — adding a fifth verb in the
+// future means adding one row here.
+func TestAgentHomeStub_AllVerbs_Return501(t *testing.T) {
+	cases := []struct {
+		name   string
+		method string
+		invoke func(c *gin.Context)
+	}{
+		{
+			name:   "ListFiles",
+			method: "GET",
+			invoke: func(c *gin.Context) { (&TemplatesHandler{}).ListFiles(c) },
+		},
+		{
+			name:   "ReadFile",
+			method: "GET",
+			invoke: func(c *gin.Context) { (&TemplatesHandler{}).ReadFile(c) },
+		},
+		{
+			name:   "WriteFile",
+			method: "PUT",
+			invoke: func(c *gin.Context) { (&TemplatesHandler{}).WriteFile(c) },
+		},
+		{
+			name:   "DeleteFile",
+			method: "DELETE",
+			invoke: func(c *gin.Context) { (&TemplatesHandler{}).DeleteFile(c) },
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			w := httptest.NewRecorder()
+			c, _ := gin.CreateTestContext(w)
+			c.Params = gin.Params{
+				{Key: "id", Value: "ws-stub"},
+				// Path param without leading slash so DeleteFile's
+				// filepath.IsAbs guard doesn't 400 before the root
+				// dispatch runs. The List/Read/Write paths strip the
+				// leading slash themselves and accept either form.
+				{Key: "path", Value: "notes.md"},
+			}
+			// WriteFile binds JSON; provide a minimal valid body so the
+			// short-circuit isn't masked by the bind-error path.
+			var body string
+			if tc.method == "PUT" {
+				body = `{"content":"x"}`
+			}
+			c.Request = httptest.NewRequest(
+				tc.method,
+				"/workspaces/ws-stub/files/notes.md?root=/agent-home",
+				strings.NewReader(body),
+			)
+			if body != "" {
+				c.Request.Header.Set("Content-Type", "application/json")
+			}
+
+			tc.invoke(c)
+
+			if w.Code != http.StatusNotImplemented {
+				t.Fatalf("expected 501, got %d: %s", w.Code, w.Body.String())
+			}
+			if !strings.Contains(w.Body.String(), "/agent-home not implemented") {
+				t.Errorf("body should contain canonical stub message; got %s", w.Body.String())
+			}
+			if strings.Contains(w.Body.String(), "workspace not found") {
+				t.Errorf("stub leaked through to DB lookup; body=%s", w.Body.String())
+			}
+		})
+	}
+}

workspace-server/internal/handlers/templates.go

@@ -18,11 +18,35 @@ import (
 )
 
 // allowedRoots are the container paths that the Files API can browse.
+//
+// `/agent-home` (added 2026-05-15, internal#425 RFC) is the container's
+// own $HOME — `/root` for openclaw, `/home/agent` for claude-code/hermes
+// — browsed via `docker exec` rather than host-side `find`. The
+// dispatch is stubbed today (returns 501); full implementation lands in
+// Phase 2b of the RFC. The allowedRoots key is added now so the canvas
+// can design its root-selector UI against the final shape and the
+// stub-vs-full transition is server-side only.
 var allowedRoots = map[string]bool{
-	"/configs":   true,
-	"/workspace": true,
-	"/home":      true,
-	"/plugins":   true,
+	"/configs":    true,
+	"/workspace":  true,
+	"/home":       true,
+	"/plugins":    true,
+	"/agent-home": true,
+}
+
+// agentHomeStubMessage is the body returned by every Files API verb
+// when `?root=/agent-home` is requested before Phase 2b lands. Keep the
+// status code 501 (Not Implemented) — the route exists, the verb is
+// understood, but the handler is unimplemented. Distinguishes from
+// 400/404 so a canvas behind a less-current server can render a clean
+// "feature pending" state instead of a generic error.
+const agentHomeStubMessage = "/agent-home not implemented yet (internal#425 RFC Phase 2b — docker-exec backend pending)"
+
+// isAgentHomeStubRequest returns true when the request targets the
+// stubbed /agent-home root. Centralised so every verb in this file
+// short-circuits with the same response shape.
+func isAgentHomeStubRequest(rootPath string) bool {
+	return rootPath == "/agent-home"
 }
 
 // maxUploadFiles limits the number of files in a single import/replace.
@@ -186,11 +210,16 @@ func (h *TemplatesHandler) List(c *gin.Context) {
 			model = raw.RuntimeConfig.Model
 		}
 
+		tier := raw.Tier
+		if h.wh != nil && h.wh.IsSaaS() {
+			tier = h.wh.DefaultTier()
+		}
+
 		templates = append(templates, templateSummary{
 			ID:                      id,
 			Name:                    raw.Name,
 			Description:             raw.Description,
-			Tier:                    raw.Tier,
+			Tier:                    tier,
 			Runtime:                 raw.Runtime,
 			Model:                   model,
 			Models:                  raw.RuntimeConfig.Models,
@@ -219,7 +248,14 @@ func (h *TemplatesHandler) ListFiles(c *gin.Context) {
 	//   ?depth= — max depth to recurse (default: 1, max: 5)
 	rootPath := c.DefaultQuery("root", "/configs")
 	if !allowedRoots[rootPath] {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "root must be one of: /configs, /workspace, /home, /plugins"})
+		c.JSON(http.StatusBadRequest, gin.H{"error": "root must be one of: /configs, /workspace, /home, /plugins, /agent-home"})
+		return
+	}
+	// /agent-home dispatch is stubbed pre-Phase-2b. Short-circuit before
+	// the DB lookup + EIC dance so a canvas exercising the new root key
+	// gets a clean 501 instead of a half-effort response.
+	if isAgentHomeStubRequest(rootPath) {
+		c.JSON(http.StatusNotImplemented, gin.H{"error": agentHomeStubMessage})
 		return
 	}
 	subPath := c.DefaultQuery("path", "")
@@ -340,6 +376,11 @@ func (h *TemplatesHandler) ListFiles(c *gin.Context) {
 		if err != nil || path == walkRoot {
 			return nil
 		}
+		// Skip symlinks to prevent path traversal via malicious symlinks
+		// inside the workspace config directory (OFFSEC-010).
+		if info.Mode()&os.ModeSymlink != 0 {
+			return nil
+		}
 		rel, _ := filepath.Rel(walkRoot, path)
 		// Enforce depth limit
 		if strings.Count(rel, string(filepath.Separator))+1 > depth {
@@ -383,7 +424,11 @@ func (h *TemplatesHandler) ReadFile(c *gin.Context) {
 	ctx := c.Request.Context()
 	rootPath := c.DefaultQuery("root", "/configs")
 	if !allowedRoots[rootPath] {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "root must be one of: /configs, /workspace, /home, /plugins"})
+		c.JSON(http.StatusBadRequest, gin.H{"error": "root must be one of: /configs, /workspace, /home, /plugins, /agent-home"})
+		return
+	}
+	if isAgentHomeStubRequest(rootPath) {
+		c.JSON(http.StatusNotImplemented, gin.H{"error": agentHomeStubMessage})
 		return
 	}
 
@@ -496,7 +541,11 @@ func (h *TemplatesHandler) WriteFile(c *gin.Context) {
 	ctx := c.Request.Context()
 	rootPath := c.DefaultQuery("root", "/configs")
 	if !allowedRoots[rootPath] {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "root must be one of: /configs, /workspace, /home, /plugins"})
+		c.JSON(http.StatusBadRequest, gin.H{"error": "root must be one of: /configs, /workspace, /home, /plugins, /agent-home"})
+		return
+	}
+	if isAgentHomeStubRequest(rootPath) {
+		c.JSON(http.StatusNotImplemented, gin.H{"error": agentHomeStubMessage})
 		return
 	}
 	var wsName, instanceID, runtime string
@@ -573,7 +622,11 @@ func (h *TemplatesHandler) DeleteFile(c *gin.Context) {
 	ctx := c.Request.Context()
 	rootPath := c.DefaultQuery("root", "/configs")
 	if !allowedRoots[rootPath] {
-		c.JSON(http.StatusBadRequest, gin.H{"error": "root must be one of: /configs, /workspace, /home, /plugins"})
+		c.JSON(http.StatusBadRequest, gin.H{"error": "root must be one of: /configs, /workspace, /home, /plugins, /agent-home"})
+		return
+	}
+	if isAgentHomeStubRequest(rootPath) {
+		c.JSON(http.StatusNotImplemented, gin.H{"error": agentHomeStubMessage})
 		return
 	}
 	var wsName, instanceID, runtime string

workspace-server/internal/handlers/templates_test.go

@@ -847,6 +847,58 @@ func TestListFiles_FallbackToHost_WithTemplate(t *testing.T) {
 	}
 }
 
+func TestListFiles_FallbackToHost_SkipsSymlinks(t *testing.T) {
+	mock := setupTestDB(t)
+	setupTestRedis(t)
+
+	tmpDir := t.TempDir()
+	tmplDir := filepath.Join(tmpDir, "test-agent")
+	if err := os.MkdirAll(tmplDir, 0755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(tmplDir, "config.yaml"), []byte("name: Test Agent\n"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	secret := filepath.Join(t.TempDir(), "secret.txt")
+	if err := os.WriteFile(secret, []byte("do-not-list"), 0600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(secret, filepath.Join(tmplDir, "leaked-secret")); err != nil {
+		t.Fatal(err)
+	}
+
+	handler := NewTemplatesHandler(tmpDir, nil, nil)
+
+	mock.ExpectQuery(`SELECT name, COALESCE\(instance_id, ''\), COALESCE\(runtime, ''\) FROM workspaces WHERE id =`).
+		WithArgs("ws-tmpl").
+		WillReturnRows(sqlmock.NewRows([]string{"name", "instance_id", "runtime"}).AddRow("Test Agent", "", ""))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "ws-tmpl"}}
+	c.Request = httptest.NewRequest("GET", "/workspaces/ws-tmpl/files", nil)
+
+	handler.ListFiles(c)
+
+	if w.Code != http.StatusOK {
+		t.Fatalf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var resp []map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatal(err)
+	}
+	for _, file := range resp {
+		if file["path"] == "leaked-secret" {
+			t.Fatalf("symlink should not be listed: %#v", resp)
+		}
+	}
+
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet sqlmock expectations: %v", err)
+	}
+}
+
 // ==================== GET /workspaces/:id/files/*path ====================
 
 func TestReadFile_PathTraversal(t *testing.T) {
@@ -1200,4 +1252,3 @@ func TestCWE78_DeleteFile_TraversalVariants(t *testing.T) {
 		})
 	}
 }
-

workspace-server/internal/handlers/terminal_test.go

@@ -340,6 +340,11 @@ func TestSSHCommandCmd_BuildsArgv(t *testing.T) {
 // a workspace must still be able to access its own terminal. The CanCommunicate
 // fast-path returns true when callerID == targetID.
 func TestTerminalConnect_KI005_AllowsOwnTerminal(t *testing.T) {
+	mock := setupTestDB(t)
+	mock.ExpectQuery("SELECT COALESCE").
+		WithArgs("ws-alice").
+		WillReturnRows(sqlmock.NewRows([]string{"instance_id"}).AddRow(""))
+
 	// CanCommunicate fast-path: callerID == targetID → returns true without DB.
 	prev := canCommunicateCheck
 	canCommunicateCheck = func(callerID, targetID string) bool { return callerID == targetID }
@@ -367,6 +372,11 @@ func TestTerminalConnect_KI005_AllowsOwnTerminal(t *testing.T) {
 // skip the CanCommunicate check entirely and fall through to the Docker auth path.
 // We assert they get the nil-docker 503 instead of 403.
 func TestTerminalConnect_KI005_SkipsCheckWithoutHeader(t *testing.T) {
+	mock := setupTestDB(t)
+	mock.ExpectQuery("SELECT COALESCE").
+		WithArgs("ws-any").
+		WillReturnRows(sqlmock.NewRows([]string{"instance_id"}).AddRow(""))
+
 	h := NewTerminalHandler(nil) // nil docker → 503 if reached
 	w := httptest.NewRecorder()
 	c, _ := gin.CreateTestContext(w)
@@ -439,6 +449,9 @@ func TestTerminalConnect_KI005_AllowsSiblingWorkspace(t *testing.T) {
 	mock.ExpectExec(`UPDATE workspace_auth_tokens SET last_used_at`).
 		WithArgs(sqlmock.AnyArg()).
 		WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectQuery("SELECT COALESCE").
+		WithArgs("ws-dev").
+		WillReturnRows(sqlmock.NewRows([]string{"instance_id"}).AddRow(""))
 
 	h := NewTerminalHandler(nil)
 	w := httptest.NewRecorder()
@@ -463,7 +476,10 @@ func TestTerminalConnect_KI005_AllowsSiblingWorkspace(t *testing.T) {
 // introduced in GH#1885: internal routing uses org tokens which are not in
 // workspace_auth_tokens, so ValidateToken would always fail for them.
 func TestKI005_OrgToken_SkipsValidateToken(t *testing.T) {
-	setupTestDB(t) // no ValidateToken ExpectQuery — none should fire
+	mock := setupTestDB(t) // no ValidateToken ExpectQuery — none should fire
+	mock.ExpectQuery("SELECT COALESCE").
+		WithArgs("ws-target").
+		WillReturnRows(sqlmock.NewRows([]string{"instance_id"}).AddRow(""))
 	prev := canCommunicateCheck
 	canCommunicateCheck = func(callerID, targetID string) bool {
 		// Simulate platform agent → target workspace (same org).
@@ -544,4 +560,3 @@ func TestSSHCommandCmd_ConnectTimeoutPresent(t *testing.T) {
 			args)
 	}
 }
-

workspace-server/internal/handlers/workspace.go

@@ -164,15 +164,14 @@ func (h *WorkspaceHandler) Create(c *gin.Context) {
 
 	id := uuid.New().String()
 	awarenessNamespace := workspaceAwarenessNamespace(id)
-	if payload.Tier == 0 {
-		// SaaS-aware default. SaaS → T4 (full host access; each
-		// workspace runs on its own sibling EC2 so the tier boundary
-		// is a Docker resource limit on the only container present —
-		// no neighbour to protect from). Self-hosted → T3 (read-write
-		// workspace mount + Docker daemon access, most templates'
-		// baseline). Lower tiers (T1 sandboxed, T2 standard) remain
-		// explicit opt-ins for low-trust agents. Matches the canvas
-		// CreateWorkspaceDialog defaults so the API and the UI agree.
+	if h.IsSaaS() {
+		// SaaS hard gate: every hosted workspace gets its own sibling
+		// EC2 instance, so T4 is the only meaningful runtime boundary.
+		// Do not trust stale clients/templates that still send T1/T2/T3.
+		payload.Tier = 4
+	} else if payload.Tier == 0 {
+		// Self-hosted default remains T3. Lower tiers (T1 sandboxed,
+		// T2 standard) stay explicit opt-ins for low-trust local agents.
 		payload.Tier = h.DefaultTier()
 	}
 

workspace-server/internal/handlers/workspace_broadcast.go

@@ -3,7 +3,7 @@ package handlers
 // workspace_broadcast.go — POST /workspaces/:id/broadcast
 //
 // Allows a workspace with broadcast_enabled=true to send a message to every
-// non-removed agent workspace in the org.  The message is:
+// non-removed agent workspace in the SAME ORG.  The message is:
 //
 //   • Persisted in each recipient's activity_logs (type='broadcast_receive')
 //     so poll-mode agents pick it up via GET /activity.
@@ -16,6 +16,11 @@ package handlers
 // Auth: WorkspaceAuth (the agent triggers this with its own bearer token).
 // The handler re-validates broadcast_enabled inside the DB lookup to prevent
 // TOCTOU — the middleware only proved the token is valid, not the ability.
+//
+// Org isolation (OFFSEC-015): recipients are scoped to the sender's org using
+// a recursive CTE that walks the parent_id chain to find the org root. This
+// prevents a compromised or misconfigured workspace from broadcasting to
+// workspaces in other tenants' orgs.
 
 import (
 	"log"
@@ -74,11 +79,49 @@ func (h *BroadcastHandler) Broadcast(c *gin.Context) {
 		return
 	}
 
-	// Collect all non-removed agent workspaces (excludes the sender itself).
-	rows, err := db.DB.QueryContext(ctx,
-		`SELECT id FROM workspaces WHERE status != 'removed' AND id != $1`,
-		senderID,
-	)
+	// Find the sender's org root by walking the parent_id chain.
+	// Workspaces with parent_id = NULL are org roots; every other workspace
+	// belongs to the org identified by its topmost ancestor.
+	var orgRootID string
+	err = db.DB.QueryRowContext(ctx, `
+		WITH RECURSIVE org_chain AS (
+			SELECT id, parent_id, id AS root_id
+			FROM workspaces
+			WHERE id = $1
+			UNION ALL
+			SELECT w.id, w.parent_id, c.root_id
+			FROM workspaces w
+			JOIN org_chain c ON w.id = c.parent_id
+		)
+		SELECT root_id FROM org_chain WHERE parent_id IS NULL LIMIT 1
+	`, senderID).Scan(&orgRootID)
+	if err != nil {
+		log.Printf("Broadcast: org root lookup for %s: %v", senderID, err)
+		c.JSON(http.StatusInternalServerError, gin.H{"error": "internal error"})
+		return
+	}
+
+	// Collect all non-removed agent workspaces in the SAME ORG (same root_id),
+	// excluding the sender itself.
+	rows, err := db.DB.QueryContext(ctx, `
+		WITH RECURSIVE org_chain AS (
+			SELECT id, parent_id, id AS root_id
+			FROM workspaces
+			WHERE parent_id IS NULL
+			UNION ALL
+			SELECT w.id, w.parent_id, c.root_id
+			FROM workspaces w
+			JOIN org_chain c ON w.parent_id = c.id
+		)
+		SELECT c.id
+		FROM org_chain c
+		WHERE c.root_id = $1
+		  AND c.id != $2
+		  AND EXISTS (
+			  SELECT 1 FROM workspaces w
+			  WHERE w.id = c.id AND w.status != 'removed'
+		  )
+	`, orgRootID, senderID)
 	if err != nil {
 		log.Printf("Broadcast: recipient query failed for %s: %v", senderID, err)
 		c.JSON(http.StatusInternalServerError, gin.H{"error": "internal error"})

workspace-server/internal/handlers/workspace_broadcast_test.go

@@ -0,0 +1,428 @@
+package handlers
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+
+	"github.com/DATA-DOG/go-sqlmock"
+	"github.com/gin-gonic/gin"
+)
+
+// -------- Org-scoped recipient query tests (OFFSEC-015) --------
+
+// TestBroadcast_OrgScopedRecipients verifies that a broadcast from Org-A does
+// NOT reach workspaces belonging to Org-B. This is the core regression test
+// for OFFSEC-015: the original query had no org filter, so a workspace in
+// Org-A could broadcast to every non-removed workspace in the entire DB,
+// including workspaces owned by other tenants.
+func TestBroadcast_OrgScopedRecipients(t *testing.T) {
+	mock := setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	// Org-A structure:
+	//   org-a-root  (parent_id = NULL)  ← sender
+	//   ├── ws-a-child
+	// Org-B structure:
+	//   org-b-root  (parent_id = NULL)
+	//   └── ws-b-child
+	senderID := "00000000-0000-0000-0000-000000000001" // org-a-root
+	wsAChild := "00000000-0000-0000-0000-000000000002"
+	// ws-b-child is in Org-B (different root); the org-scoped query MUST NOT include it.
+
+	// 1. Sender lookup
+	mock.ExpectQuery(`SELECT name, broadcast_enabled FROM workspaces WHERE id = \$1 AND status != 'removed'`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"name", "broadcast_enabled"}).AddRow("Org-A Root", true))
+
+	// 2. Org root lookup — sender is its own root (parent_id = NULL)
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"root_id"}).AddRow(senderID))
+
+	// 3. Org-scoped recipient query — MUST include org filter so ws-b-child is NOT included.
+	// The query joins on org_chain.root_id = orgRootID, which scopes to Org-A only.
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID, senderID). // orgRootID, senderID (EXCLUDED)
+		WillReturnRows(sqlmock.NewRows([]string{"id"}).AddRow(wsAChild)) // only Org-A child
+
+	// Activity log inserts
+	mock.ExpectExec(`INSERT INTO activity_logs`).WithArgs(wsAChild, senderID, sqlmock.AnyArg()).WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectExec(`INSERT INTO activity_logs`).WithArgs(senderID, sqlmock.AnyArg()).WillReturnResult(sqlmock.NewResult(0, 1))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: senderID}}
+	body := `{"message":"hello from org-a"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces/"+senderID+"/broadcast", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+
+	var resp map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to unmarshal response: %v", err)
+	}
+	if resp["status"] != "sent" {
+		t.Errorf("expected status 'sent', got %v", resp["status"])
+	}
+	// ws-b-child is in a DIFFERENT org — the org-scoped query MUST NOT include it.
+	// If it were included, the mock would have an unmet expectation.
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet mock expectations — cross-org workspace was included in broadcast: %v", err)
+	}
+}
+
+// TestBroadcast_OrgScoped_OrgRootSender verifies that when the sender IS the
+// org root (parent_id = NULL), broadcasts still reach sibling workspaces.
+func TestBroadcast_OrgScoped_OrgRootSender(t *testing.T) {
+	mock := setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	senderID := "00000000-0000-0000-0000-000000000001" // org-a-root
+	siblingID := "00000000-0000-0000-0000-000000000002"
+
+	mock.ExpectQuery(`SELECT name, broadcast_enabled FROM workspaces WHERE id = \$1 AND status != 'removed'`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"name", "broadcast_enabled"}).AddRow("Root Agent", true))
+
+	// Sender is the org root — CTE returns sender's own ID as root
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"root_id"}).AddRow(senderID))
+
+	// Recipients in same org, excluding sender
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID, senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"id"}).AddRow(siblingID))
+
+	mock.ExpectExec(`INSERT INTO activity_logs`).WithArgs(siblingID, senderID, sqlmock.AnyArg()).WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectExec(`INSERT INTO activity_logs`).WithArgs(senderID, sqlmock.AnyArg()).WillReturnResult(sqlmock.NewResult(0, 1))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: senderID}}
+	body := `{"message":"hello siblings"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces/"+senderID+"/broadcast", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet expectations: %v", err)
+	}
+}
+
+// TestBroadcast_OrgScoped_ChildWorkspaceSender verifies that a non-root child
+// workspace can broadcast to siblings in the same org.
+func TestBroadcast_OrgScoped_ChildWorkspaceSender(t *testing.T) {
+	mock := setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	orgRootID := "00000000-0000-0000-0000-000000000001"
+	senderID := "00000000-0000-0000-0000-000000000002" // child workspace
+	siblingID := "00000000-0000-0000-0000-000000000003"
+
+	mock.ExpectQuery(`SELECT name, broadcast_enabled FROM workspaces WHERE id = \$1 AND status != 'removed'`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"name", "broadcast_enabled"}).AddRow("Child Agent", true))
+
+	// Org root lookup — walk up to find org-a-root
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"root_id"}).AddRow(orgRootID))
+
+	// Recipients: same org, excluding sender
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(orgRootID, senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"id"}).AddRow(siblingID))
+
+	mock.ExpectExec(`INSERT INTO activity_logs`).WithArgs(siblingID, senderID, sqlmock.AnyArg()).WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectExec(`INSERT INTO activity_logs`).WithArgs(senderID, sqlmock.AnyArg()).WillReturnResult(sqlmock.NewResult(0, 1))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: senderID}}
+	body := `{"message":"child broadcasting"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces/"+senderID+"/broadcast", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet expectations: %v", err)
+	}
+}
+
+// -------- Non-regression cases --------
+
+func TestBroadcast_NotFound(t *testing.T) {
+	mock := setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	senderID := "00000000-0000-0000-0000-000000000099"
+	// UUID is valid, but no workspace row matches
+	mock.ExpectQuery(`SELECT name, broadcast_enabled FROM workspaces WHERE id = \$1 AND status != 'removed'`).
+		WithArgs(senderID).
+		WillReturnError(errors.New("workspace not found"))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: senderID}}
+	body := `{"message":"test"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces/"+senderID+"/broadcast", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusNotFound {
+		t.Errorf("expected 404, got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet expectations: %v", err)
+	}
+}
+
+func TestBroadcast_Disabled(t *testing.T) {
+	mock := setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	senderID := "00000000-0000-0000-0000-000000000001"
+	mock.ExpectQuery(`SELECT name, broadcast_enabled FROM workspaces WHERE id = \$1 AND status != 'removed'`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"name", "broadcast_enabled"}).AddRow("Disabled Agent", false))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: senderID}}
+	body := `{"message":"should not send"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces/"+senderID+"/broadcast", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusForbidden {
+		t.Errorf("expected 403, got %d: %s", w.Code, w.Body.String())
+	}
+	var resp map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to unmarshal: %v", err)
+	}
+	if resp["error"] != "broadcast_disabled" {
+		t.Errorf("expected error 'broadcast_disabled', got %v", resp["error"])
+	}
+}
+
+func TestBroadcast_EmptyOrg_NoRecipients(t *testing.T) {
+	mock := setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	senderID := "00000000-0000-0000-0000-000000000001" // org root, only workspace in org
+
+	mock.ExpectQuery(`SELECT name, broadcast_enabled FROM workspaces WHERE id = \$1 AND status != 'removed'`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"name", "broadcast_enabled"}).AddRow("Lone Root", true))
+
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"root_id"}).AddRow(senderID))
+
+	// No other workspaces in this org
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID, senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"id"}))
+
+	mock.ExpectExec(`INSERT INTO activity_logs`).WithArgs(senderID, sqlmock.AnyArg()).WillReturnResult(sqlmock.NewResult(0, 1))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: senderID}}
+	body := `{"message":"hello org"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces/"+senderID+"/broadcast", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+	var resp map[string]interface{}
+	if err := json.Unmarshal(w.Body.Bytes(), &resp); err != nil {
+		t.Fatalf("failed to unmarshal: %v", err)
+	}
+	if resp["delivered"] != float64(0) {
+		t.Errorf("expected delivered=0, got %v", resp["delivered"])
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet expectations: %v", err)
+	}
+}
+
+func TestBroadcast_InvalidWorkspaceID(t *testing.T) {
+	setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "not-a-uuid"}}
+	body := `{"message":"test"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces/not-a-uuid/broadcast", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+func TestBroadcast_MissingMessage(t *testing.T) {
+	setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: "00000000-0000-0000-0000-000000000001"}}
+	c.Request = httptest.NewRequest("POST", "/workspaces/00000000-0000-0000-0000-000000000001/broadcast", bytes.NewBufferString("{}"))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusBadRequest {
+		t.Errorf("expected 400, got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+// TestBroadcast_OrgRootLookupFails verifies that if the recursive CTE for
+// finding the org root errors, the handler returns 500 instead of proceeding
+// with an un-scoped query that would broadcast to all orgs.
+func TestBroadcast_OrgRootLookupFails(t *testing.T) {
+	mock := setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	senderID := "00000000-0000-0000-0000-000000000001"
+
+	mock.ExpectQuery(`SELECT name, broadcast_enabled FROM workspaces WHERE id = \$1 AND status != 'removed'`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"name", "broadcast_enabled"}).AddRow("Root Agent", true))
+
+	// Org root CTE fails
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID).
+		WillReturnError(context.DeadlineExceeded)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: senderID}}
+	body := `{"message":"should not broadcast"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces/"+senderID+"/broadcast", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusInternalServerError {
+		t.Errorf("expected 500, got %d: %s", w.Code, w.Body.String())
+	}
+	// The recipient query MUST NOT be called — it would broadcast cross-org
+	// if the org root lookup failed silently.
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet expectations: %v", err)
+	}
+}
+
+// TestBroadcast_OrgScoped_SelfBroadcastExcluded verifies that broadcasting
+// from a workspace does not send a broadcast_receive to the sender itself
+// (the sender logs broadcast_sent, not broadcast_receive).
+func TestBroadcast_OrgScoped_SelfBroadcastExcluded(t *testing.T) {
+	mock := setupTestDB(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewBroadcastHandler(broadcaster)
+
+	senderID := "00000000-0000-0000-0000-000000000001"
+	peerID := "00000000-0000-0000-0000-000000000002"
+
+	mock.ExpectQuery(`SELECT name, broadcast_enabled FROM workspaces WHERE id = \$1 AND status != 'removed'`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"name", "broadcast_enabled"}).AddRow("Root Agent", true))
+
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"root_id"}).AddRow(senderID))
+
+	// Recipient query MUST exclude sender via id != senderID
+	mock.ExpectQuery(`WITH RECURSIVE org_chain AS`).
+		WithArgs(senderID, senderID).
+		WillReturnRows(sqlmock.NewRows([]string{"id"}).AddRow(peerID))
+
+	// Peer receives broadcast_receive
+	mock.ExpectExec(`INSERT INTO activity_logs`).WithArgs(peerID, senderID, sqlmock.AnyArg()).WillReturnResult(sqlmock.NewResult(0, 1))
+	// Sender logs broadcast_sent (NOT broadcast_receive)
+	mock.ExpectExec(`INSERT INTO activity_logs`).WithArgs(senderID, sqlmock.AnyArg()).WillReturnResult(sqlmock.NewResult(0, 1))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	c.Params = gin.Params{{Key: "id", Value: senderID}}
+	body := `{"message":"no echo to self"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces/"+senderID+"/broadcast", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Broadcast(c)
+
+	if w.Code != http.StatusOK {
+		t.Errorf("expected 200, got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet expectations: %v", err)
+	}
+}
+
+// TestBroadcast_Truncate tests that messages are truncated with the Unicode ellipsis
+// TestBroadcast_Truncate tests that messages are truncated with the Unicode ellipsis
+// character (U+2026) when len(msg) > max. The truncated output is max runes + "…",
+// so truncating a 48-char string at max=20 produces 21 characters (20 runes + "…").
+func TestBroadcast_Truncate(t *testing.T) {
+	cases := []struct {
+		msg    string
+		max    int
+		expect string
+	}{
+		{"short", 120, "short"}, // under max — no truncation
+		// exactly120chars (15) + 105 ones = 120 chars; at max=120 → unchanged
+		{"exactly120chars1111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111", 120, "exactly120chars111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111…"},
+		// "this is a longer mes" = 20 runes; + "…" = 21 chars
+		{"this is a longer message that needs truncating", 20, "this is a longer mes…"},
+		// at-max boundary: 20 chars at max=20 → no truncation
+		{"exactly twenty chars", 20, "exactly twenty chars"},
+		// over max: 11 chars at max=10 → 10 + "…" = 11
+		{"hello world!", 10, "hello worl…"},
+	}
+	for _, tc := range cases {
+		result := broadcastTruncate(tc.msg, tc.max)
+		if result != tc.expect {
+			t.Errorf("broadcastTruncate(%q, %d) = %q; want %q", tc.msg, tc.max, result, tc.expect)
+		}
+	}
+}

workspace-server/internal/handlers/workspace_provision.go

@@ -15,6 +15,7 @@ import (
 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/models"
 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/provisioner"
 	"github.com/Molecule-AI/molecule-monorepo/platform/internal/wsauth"
+	"gopkg.in/yaml.v3"
 )
 
 // logProvisionPanic is the deferred recover at the top of every provision
@@ -472,9 +473,10 @@ func configDirName(workspaceID string) string {
 // runtime means bumping both this list and the Docker image tags.
 // knownRuntimes is populated from manifest.json at service init (see
 // runtime_registry.go). The package init order is:
-//   1. var knownRuntimes = fallbackRuntimes
-//   2. init() calls initKnownRuntimes() which replaces it if
-//      manifest.json is readable.
+//  1. var knownRuntimes = fallbackRuntimes
+//  2. init() calls initKnownRuntimes() which replaces it if
+//     manifest.json is readable.
+//
 // The fallback matters for unit tests that don't mount the manifest.
 //
 // "external" is a first-class runtime that intentionally does NOT
@@ -539,6 +541,9 @@ func (h *WorkspaceHandler) ensureDefaultConfig(workspaceID string, payload model
 		// org_import.go; consolidating prevents silent drift.
 		model = models.DefaultModel(runtime)
 	}
+	if runtime == "claude-code" {
+		model = normalizeClaudeCodeModel(model)
+	}
 
 	// Sanitize name/role/model for YAML safety — always double-quote so
 	// a crafted value with a newline or colon can't terminate the scalar
@@ -554,6 +559,11 @@ func (h *WorkspaceHandler) ensureDefaultConfig(workspaceID string, payload model
 	quoteModel := yamlQuote(model)
 	configYAML := fmt.Sprintf("name: %s\ndescription: %s\nversion: 1.0.0\ntier: %d\nruntime: %s\n",
 		quoteName, quoteRole, payload.Tier, runtime)
+	if runtime == "claude-code" {
+		if providersYAML := h.defaultTemplateProvidersYAML(runtime); providersYAML != "" {
+			configYAML += providersYAML + "\n"
+		}
+	}
 
 	// Model always at top level — config.py reads raw["model"] for all runtimes.
 	configYAML += fmt.Sprintf("model: %s\n", quoteModel)
@@ -563,7 +573,11 @@ func (h *WorkspaceHandler) ensureDefaultConfig(workspaceID string, payload model
 	// and preflight already validates that the env vars are present before
 	// the agent loop starts.  Hardcoding token names here caused #1028
 	// (expired CLAUDE_CODE_OAUTH_TOKEN baked into config.yaml).
-	configYAML += "runtime_config:\n  timeout: 0\n"
+	configYAML += "runtime_config:\n"
+	if runtime == "claude-code" {
+		configYAML += fmt.Sprintf("  model: %s\n", quoteModel)
+	}
+	configYAML += "  timeout: 0\n"
 
 	files["config.yaml"] = []byte(configYAML)
 
@@ -571,6 +585,60 @@ func (h *WorkspaceHandler) ensureDefaultConfig(workspaceID string, payload model
 	return files
 }
 
+func normalizeClaudeCodeModel(model string) string {
+	model = strings.TrimSpace(model)
+	if before, after, ok := strings.Cut(model, "/"); ok && before != "" && after != "" {
+		return after
+	}
+	return model
+}
+
+func (h *WorkspaceHandler) defaultTemplateProvidersYAML(runtime string) string {
+	if h.configsDir == "" {
+		return ""
+	}
+	templateName := runtime + "-default"
+	templatePath, err := resolveInsideRoot(h.configsDir, templateName)
+	if err != nil {
+		log.Printf("Provisioner: default template providers skipped for runtime %s: %v", runtime, err)
+		return ""
+	}
+	data, err := os.ReadFile(filepath.Join(templatePath, "config.yaml"))
+	if err != nil {
+		return ""
+	}
+
+	var root yaml.Node
+	if err := yaml.Unmarshal(data, &root); err != nil {
+		log.Printf("Provisioner: default template providers skipped for runtime %s: invalid YAML: %v", runtime, err)
+		return ""
+	}
+	if len(root.Content) == 0 || root.Content[0].Kind != yaml.MappingNode {
+		return ""
+	}
+
+	mapping := root.Content[0]
+	for i := 0; i+1 < len(mapping.Content); i += 2 {
+		if mapping.Content[i].Value != "providers" {
+			continue
+		}
+		out := yaml.Node{
+			Kind: yaml.MappingNode,
+			Content: []*yaml.Node{
+				{Kind: yaml.ScalarNode, Value: "providers"},
+				mapping.Content[i+1],
+			},
+		}
+		encoded, err := yaml.Marshal(&out)
+		if err != nil {
+			log.Printf("Provisioner: default template providers skipped for runtime %s: marshal failed: %v", runtime, err)
+			return ""
+		}
+		return strings.TrimRight(string(encoded), "\n")
+	}
+	return ""
+}
+
 // deriveProviderFromModelSlug maps a hermes-agent model slug prefix to
 // its provider name — a Go translation of the case statement in
 // workspace-configs-templates/hermes/scripts/derive-provider.sh that we

workspace-server/internal/handlers/workspace_provision_auto_test.go

@@ -144,6 +144,7 @@ func TestProvisionWorkspaceAuto_RoutesToCPWhenSet(t *testing.T) {
 	rec := &trackingCPProv{startErr: errors.New("simulated CP rejection")}
 	bcast := &concurrentSafeBroadcaster{}
 	h := NewWorkspaceHandler(bcast, nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, h)
 	h.SetCPProvisioner(rec)
 
 	wsID := "ws-routes-to-cp-0123456789abcdef"
@@ -595,6 +596,7 @@ func TestRestartWorkspaceAuto_RoutesToCPWhenSet(t *testing.T) {
 
 	// Mock DB so cpStopWithRetry can run without a real Postgres.
 	mock := setupTestDB(t)
+	waitForHandlerAsyncBeforeDBCleanup(t, h)
 	mock.MatchExpectationsInOrder(false)
 	// provisionWorkspaceCP runs in the goroutine and will hit secrets
 	// SELECTs + UPDATE workspace as failed (we make CP Start return
@@ -670,6 +672,7 @@ func TestRestartWorkspaceAuto_RoutesToDockerWhenOnlyDocker(t *testing.T) {
 
 	bcast := &concurrentSafeBroadcaster{}
 	h := NewWorkspaceHandler(bcast, nil, "http://localhost:8080", t.TempDir())
+	waitForHandlerAsyncBeforeDBCleanup(t, h)
 	stub := &stoppingLocalProv{}
 	h.provisioner = stub
 

workspace-server/internal/handlers/workspace_provision_test.go

@@ -2,6 +2,7 @@ package handlers
 
 import (
 	"context"
+	"database/sql"
 	"fmt"
 	"net/http"
 	"os"
@@ -260,6 +261,67 @@ func TestEnsureDefaultConfig_ClaudeCode(t *testing.T) {
 	}
 }
 
+func TestEnsureDefaultConfig_ClaudeCodeCopiesProviderRegistry(t *testing.T) {
+	broadcaster := newTestBroadcaster()
+	configsDir := t.TempDir()
+	templateDir := filepath.Join(configsDir, "claude-code-default")
+	if err := os.MkdirAll(templateDir, 0o755); err != nil {
+		t.Fatalf("mkdir template: %v", err)
+	}
+	if err := os.WriteFile(filepath.Join(templateDir, "config.yaml"), []byte(`
+name: Claude Code Agent
+runtime: claude-code
+providers:
+  - name: anthropic-oauth
+    auth_mode: oauth
+    model_aliases: [sonnet]
+    auth_env: [CLAUDE_CODE_OAUTH_TOKEN]
+  - name: minimax
+    auth_mode: third_party_anthropic_compat
+    model_prefixes: [minimax-]
+    base_url: https://api.minimax.io/anthropic
+    auth_env: [MINIMAX_API_KEY, ANTHROPIC_AUTH_TOKEN]
+runtime_config:
+  model: sonnet
+`), 0o644); err != nil {
+		t.Fatalf("write template: %v", err)
+	}
+	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", configsDir)
+
+	files := handler.ensureDefaultConfig("ws-code-123", models.CreateWorkspacePayload{
+		Name:    "Code Agent",
+		Tier:    4,
+		Runtime: "claude-code",
+		Model:   "minimax/MiniMax-M2.7",
+	})
+
+	var parsed struct {
+		Model     string `yaml:"model"`
+		Providers []struct {
+			Name          string   `yaml:"name"`
+			ModelPrefixes []string `yaml:"model_prefixes"`
+		} `yaml:"providers"`
+		RuntimeConfig struct {
+			Model string `yaml:"model"`
+		} `yaml:"runtime_config"`
+	}
+	if err := yaml.Unmarshal(files["config.yaml"], &parsed); err != nil {
+		t.Fatalf("generated YAML invalid: %v\n%s", err, files["config.yaml"])
+	}
+	if parsed.Model != "MiniMax-M2.7" {
+		t.Fatalf("top-level model = %q, want MiniMax-M2.7\n%s", parsed.Model, files["config.yaml"])
+	}
+	if parsed.RuntimeConfig.Model != "MiniMax-M2.7" {
+		t.Fatalf("runtime_config.model = %q, want MiniMax-M2.7\n%s", parsed.RuntimeConfig.Model, files["config.yaml"])
+	}
+	if len(parsed.Providers) != 2 {
+		t.Fatalf("providers len = %d, want 2\n%s", len(parsed.Providers), files["config.yaml"])
+	}
+	if parsed.Providers[1].Name != "minimax" || len(parsed.Providers[1].ModelPrefixes) != 1 || parsed.Providers[1].ModelPrefixes[0] != "minimax-" {
+		t.Fatalf("minimax provider registry not preserved: %+v\n%s", parsed.Providers, files["config.yaml"])
+	}
+}
+
 func TestEnsureDefaultConfig_CustomModel(t *testing.T) {
 	broadcaster := newTestBroadcaster()
 	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", t.TempDir())
@@ -634,6 +696,11 @@ func TestSeedInitialMemories_EmptyMemoriesNil(t *testing.T) {
 // ==================== buildProvisionerConfig ====================
 
 func TestBuildProvisionerConfig_BasicFields(t *testing.T) {
+	mock := setupTestDB(t)
+	mock.ExpectQuery(`SELECT COALESCE\(workspace_dir`).
+		WithArgs("ws-basic").
+		WillReturnRows(sqlmock.NewRows([]string{"workspace_dir", "workspace_access"}).AddRow("", "none"))
+
 	broadcaster := newTestBroadcaster()
 	tmpDir := t.TempDir()
 	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", tmpDir)
@@ -678,6 +745,14 @@ func TestBuildProvisionerConfig_BasicFields(t *testing.T) {
 }
 
 func TestBuildProvisionerConfig_WorkspacePathFromEnv(t *testing.T) {
+	mock := setupTestDB(t)
+	mock.ExpectQuery(`SELECT COALESCE\(workspace_dir`).
+		WithArgs("ws-env").
+		WillReturnError(sql.ErrNoRows)
+	mock.ExpectQuery(`SELECT digest FROM runtime_image_pins`).
+		WithArgs("claude-code").
+		WillReturnError(sql.ErrNoRows)
+
 	broadcaster := newTestBroadcaster()
 	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", t.TempDir())
 

workspace-server/internal/handlers/workspace_test.go

@@ -414,6 +414,44 @@ func TestWorkspaceCreate_DefaultsApplied(t *testing.T) {
 	}
 }
 
+func TestWorkspaceCreate_SaaSHardForcesTier4(t *testing.T) {
+	mock := setupTestDB(t)
+	setupTestRedis(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", t.TempDir())
+	handler.SetCPProvisioner(&trackingCPProv{})
+
+	mock.ExpectBegin()
+	mock.ExpectExec("INSERT INTO workspaces").
+		WithArgs(sqlmock.AnyArg(), "SaaS External Agent", nil, 4, "external", sqlmock.AnyArg(), (*string)(nil), nil, "none", (*int64)(nil), models.DefaultMaxConcurrentTasks, "push").
+		WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectCommit()
+	mock.ExpectExec("INSERT INTO canvas_layouts").
+		WithArgs(sqlmock.AnyArg(), float64(0), float64(0)).
+		WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectExec("INSERT INTO structure_events").
+		WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectExec("UPDATE workspaces SET url").
+		WillReturnResult(sqlmock.NewResult(0, 1))
+	mock.ExpectExec("INSERT INTO structure_events").
+		WillReturnResult(sqlmock.NewResult(0, 1))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	body := `{"name":"SaaS External Agent","runtime":"external","external":true,"url":"https://example.com/agent","tier":2}`
+	c.Request = httptest.NewRequest("POST", "/workspaces", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Create(c)
+
+	if w.Code != http.StatusCreated {
+		t.Errorf("expected status 201, got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet sqlmock expectations: %v", err)
+	}
+}
+
 // TestWorkspaceCreate_WithSecrets_Persists asserts that secrets in the create
 // payload are written to workspace_secrets inside the same transaction as the
 // workspace row, and that the handler returns 201.

workspace-server/internal/provisioner/cp_provisioner.go

@@ -178,12 +178,21 @@ func (p *CPProvisioner) Start(ctx context.Context, cfg WorkspaceConfig) (string,
 	// /admin/liveness and other admin-gated platform endpoints (core#831).
 	// p.adminToken is read from os.Getenv("ADMIN_TOKEN") at provisioner creation;
 	// it is also used for CP→platform HTTP auth but those are separate concerns.
-	env := cfg.EnvVars
-	if p.adminToken != "" {
-		env = make(map[string]string, len(cfg.EnvVars)+1)
-		for k, v := range cfg.EnvVars {
-			env[k] = v
+	//
+	// Forensic #145 hardening: tenant workspaces run on EC2 via this path, so
+	// the SCM-write-token denylist (see buildContainerEnv) is enforced here
+	// too. Always build a filtered copy — never pass cfg.EnvVars through
+	// verbatim — so a latent persona-merged GITEA_TOKEN can't reach the
+	// tenant container regardless of whether ADMIN_TOKEN is set.
+	env := make(map[string]string, len(cfg.EnvVars)+1)
+	for k, v := range cfg.EnvVars {
+		if isSCMWriteTokenKey(k) {
+			log.Printf("CPProvisioner.Start: dropped SCM-write credential %q from tenant workspace env (forensic #145 guard)", k)
+			continue
 		}
+		env[k] = v
+	}
+	if p.adminToken != "" {
 		env["ADMIN_TOKEN"] = p.adminToken
 	}
 	// Collect template files and generated configs, with OFFSEC-010 guards:
@@ -343,6 +352,7 @@ func collectCPConfigFiles(cfg WorkspaceConfig) (map[string]string, error) {
 	}
 	return files, nil
 }
+
 // Stop terminates the workspace's EC2 instance via the control plane.
 //
 // Looks up the actual EC2 instance_id from the workspaces table before
@@ -497,7 +507,9 @@ func (p *CPProvisioner) IsRunning(ctx context.Context, workspaceID string) (bool
 		// Don't leak the body — upstream errors may echo headers.
 		return true, fmt.Errorf("cp provisioner: status: unexpected %d", resp.StatusCode)
 	}
-	var result struct{ State string `json:"state"` }
+	var result struct {
+		State string `json:"state"`
+	}
 	// Cap body read at 64 KiB for parity with Start — a misconfigured
 	// or compromised CP streaming a huge body could otherwise exhaust
 	// memory in this hot path (called reactively per-request from

workspace-server/internal/provisioner/cp_provisioner_test.go

@@ -217,6 +217,59 @@ func TestStart_HappyPath(t *testing.T) {
 	}
 }
 
+func TestStart_SendsTemplateAndGeneratedConfigFiles(t *testing.T) {
+	tmpl := t.TempDir()
+	if err := os.WriteFile(filepath.Join(tmpl, "config.yaml"), []byte("name: template\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(tmpl, "adapter.py"), bytes.Repeat([]byte("x"), cpConfigFilesMaxBytes), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Mkdir(filepath.Join(tmpl, "prompts"), 0o700); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(tmpl, "prompts", "system.md"), []byte("hello"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	var body cpProvisionRequest
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if err := json.NewDecoder(r.Body).Decode(&body); err != nil {
+			t.Errorf("decode request: %v", err)
+		}
+		w.WriteHeader(http.StatusCreated)
+		_, _ = io.WriteString(w, `{"instance_id":"i-abc123","state":"pending"}`)
+	}))
+	defer srv.Close()
+
+	p := &CPProvisioner{baseURL: srv.URL, orgID: "org-1", httpClient: srv.Client()}
+	_, err := p.Start(context.Background(), WorkspaceConfig{
+		WorkspaceID:  "ws-1",
+		Runtime:      "claude-code",
+		Tier:         4,
+		PlatformURL:  "http://tenant",
+		TemplatePath: tmpl,
+		ConfigFiles: map[string][]byte{
+			"config.yaml": []byte("name: generated\n"),
+		},
+	})
+	if err != nil {
+		t.Fatalf("Start: %v", err)
+	}
+
+	wantConfig := base64.StdEncoding.EncodeToString([]byte("name: generated\n"))
+	if got := body.ConfigFiles["config.yaml"]; got != wantConfig {
+		t.Errorf("config.yaml payload = %q, want generated override %q", got, wantConfig)
+	}
+	wantPrompt := base64.StdEncoding.EncodeToString([]byte("hello"))
+	if got := body.ConfigFiles["prompts/system.md"]; got != wantPrompt {
+		t.Errorf("prompt payload = %q, want %q", got, wantPrompt)
+	}
+	if _, ok := body.ConfigFiles["adapter.py"]; ok {
+		t.Error("non-config template file adapter.py must not be sent to CP")
+	}
+}
+
 // TestStart_Non201ReturnsStructuredError — when CP returns 401 with a
 // structured {"error":"..."} body, Start surfaces that error message.
 // Verifies the defense against log-leaking raw upstream bodies.
@@ -519,9 +572,9 @@ func TestStop_4xxResponseSurfacesError(t *testing.T) {
 func TestStop_2xxVariantsAllSucceed(t *testing.T) {
 	primeInstanceIDLookup(t, map[string]string{"ws-1": "i-ok"})
 	for _, code := range []int{
-		http.StatusOK,           // 200
-		http.StatusAccepted,     // 202
-		http.StatusNoContent,    // 204
+		http.StatusOK,        // 200
+		http.StatusAccepted,  // 202
+		http.StatusNoContent, // 204
 	} {
 		srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, _ *http.Request) {
 			w.WriteHeader(code)
@@ -589,11 +642,11 @@ func TestIsRunning_ParsesStateField(t *testing.T) {
 			_, _ = io.WriteString(w, `{"state":"`+state+`"}`)
 		}))
 		p := &CPProvisioner{
-			baseURL:    srv.URL,
-			orgID:      "org-1",
+			baseURL:      srv.URL,
+			orgID:        "org-1",
 			sharedSecret: "s3cret",
 			adminToken:   "tok-xyz",
-			httpClient: srv.Client(),
+			httpClient:   srv.Client(),
 		}
 		got, err := p.IsRunning(context.Background(), "ws-1")
 		srv.Close()

workspace-server/internal/provisioner/provisioner.go

@@ -591,6 +591,28 @@ func ValidateWorkspaceAccess(access, workspacePath string) error {
 	}
 }
 
+// scmWriteTokenKeys is the explicit denylist of environment variable names
+// that carry a Git SCM *write* credential (push / merge / approve). These
+// must never reach a tenant workspace container — see the forensic #145
+// rationale in buildContainerEnv. Kept as an exact-match set rather than a
+// substring/prefix heuristic so the guard is auditable and can't silently
+// over-strip a legitimately-named var.
+var scmWriteTokenKeys = map[string]struct{}{
+	"GITEA_TOKEN":     {},
+	"GITHUB_TOKEN":    {},
+	"GH_TOKEN":        {}, // gh CLI honours GH_TOKEN as a GITHUB_TOKEN alias
+	"GITLAB_TOKEN":    {},
+	"GL_TOKEN":        {}, // glab CLI alias
+	"BITBUCKET_TOKEN": {},
+}
+
+// isSCMWriteTokenKey reports whether an env var name is a known Git SCM
+// write credential that must be stripped from tenant workspace env.
+func isSCMWriteTokenKey(key string) bool {
+	_, ok := scmWriteTokenKeys[key]
+	return ok
+}
+
 // buildContainerEnv assembles the initial environment variables injected
 // into every workspace container.
 //
@@ -627,6 +649,21 @@ func buildContainerEnv(cfg WorkspaceConfig) []string {
 		env = append(env, fmt.Sprintf("AWARENESS_URL=%s", cfg.AwarenessURL))
 	}
 	for k, v := range cfg.EnvVars {
+		// Forensic #145 hardening: tenant workspace containers run
+		// agent-controlled code and must NEVER receive a Git SCM *write*
+		// credential. Without merge/approve creds in-container the
+		// two-eyes review gate is structurally self-bypass-proof — an
+		// agent that forges an approval has no token to act on it. A
+		// latent path exists (loadPersonaEnvFile merges a per-role
+		// persona `GITEA_TOKEN` into cfg.EnvVars when MOLECULE_PERSONA_ROOT
+		// is set on a tenant host); it is inert today (persona dirs are
+		// operator-host-only) but unguarded. Strip SCM-write tokens here
+		// by construction so the invariant holds regardless of whether
+		// that path ever becomes reachable.
+		if isSCMWriteTokenKey(k) {
+			log.Printf("buildContainerEnv: dropped SCM-write credential %q from workspace env (forensic #145 guard)", k)
+			continue
+		}
 		env = append(env, fmt.Sprintf("%s=%s", k, v))
 	}
 	// Inject ADMIN_TOKEN from the platform server's environment so workspace
@@ -773,6 +810,15 @@ func ApplyTierConfig(hostCfg *container.HostConfig, cfg WorkspaceConfig, configM
 
 // CopyTemplateToContainer copies files from a host directory into /configs in the container.
 func (p *Provisioner) CopyTemplateToContainer(ctx context.Context, containerID, templatePath string) error {
+	buf, err := buildTemplateTar(templatePath)
+	if err != nil {
+		return err
+	}
+
+	return p.cli.CopyToContainer(ctx, containerID, "/configs", buf, container.CopyToContainerOptions{})
+}
+
+func buildTemplateTar(templatePath string) (*bytes.Buffer, error) {
 	// Resolve symlinks at the root before walking. filepath.Walk does
 	// NOT follow a symlink that IS the root — it Lstats the path, sees
 	// a symlink (non-directory), and emits exactly one entry without
@@ -795,6 +841,15 @@ func (p *Provisioner) CopyTemplateToContainer(ctx context.Context, containerID,
 		if err != nil {
 			return err
 		}
+		// OFFSEC-010: skip symlinks to prevent path traversal via malicious
+		// template symlinks (e.g. template/.ssh → /root/.ssh). filepath.Walk
+		// follows symlinks by default, so without this guard a crafted symlink
+		// inside the template directory could escape to include arbitrary host
+		// files in the tar archive. We intentionally skip rather than error so
+		// a broken symlink in an org template is a silent no-op.
+		if info.Mode()&os.ModeSymlink != 0 {
+			return nil
+		}
 		rel, err := filepath.Rel(templatePath, path)
 		if err != nil {
 			return err
@@ -835,13 +890,13 @@ func (p *Provisioner) CopyTemplateToContainer(ctx context.Context, containerID,
 		return nil
 	})
 	if err != nil {
-		return fmt.Errorf("failed to create tar from %s: %w", templatePath, err)
+		return nil, fmt.Errorf("failed to create tar from %s: %w", templatePath, err)
 	}
 	if err := tw.Close(); err != nil {
-		return fmt.Errorf("failed to close tar writer: %w", err)
+		return nil, fmt.Errorf("failed to close tar writer: %w", err)
 	}
 
-	return p.cli.CopyToContainer(ctx, containerID, "/configs", &buf, container.CopyToContainerOptions{})
+	return &buf, nil
 }
 
 // WriteFilesToContainer writes in-memory files into /configs in the container.

workspace-server/internal/provisioner/provisioner_test.go

@@ -1,7 +1,9 @@
 package provisioner
 
 import (
+	"archive/tar"
 	"errors"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
@@ -62,6 +64,72 @@ func TestValidateConfigSource_TemplateIsDirName(t *testing.T) {
 	}
 }
 
+func TestStartSeedsConfigsBeforeContainerStart(t *testing.T) {
+	src, err := os.ReadFile("provisioner.go")
+	if err != nil {
+		t.Fatalf("read provisioner.go: %v", err)
+	}
+	text := string(src)
+	copyTemplate := strings.Index(text, "p.CopyTemplateToContainer(ctx, resp.ID, cfg.TemplatePath)")
+	writeFiles := strings.Index(text, "p.WriteFilesToContainer(ctx, resp.ID, cfg.ConfigFiles)")
+	start := strings.Index(text, "p.cli.ContainerStart(ctx, resp.ID, container.StartOptions{})")
+
+	if copyTemplate < 0 || writeFiles < 0 || start < 0 {
+		t.Fatalf("expected Start to copy template, write config files, and start container")
+	}
+	if copyTemplate >= start || writeFiles >= start {
+		t.Fatalf("config seeding must happen before ContainerStart: copyTemplate=%d writeFiles=%d start=%d", copyTemplate, writeFiles, start)
+	}
+}
+
+func TestBuildTemplateTar_SkipsSymlinks(t *testing.T) {
+	dir := t.TempDir()
+	if err := os.WriteFile(filepath.Join(dir, "config.yaml"), []byte("name: safe\n"), 0644); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+	outside := filepath.Join(t.TempDir(), "secret.txt")
+	if err := os.WriteFile(outside, []byte("do-not-copy\n"), 0644); err != nil {
+		t.Fatalf("write outside target: %v", err)
+	}
+	if err := os.Symlink(outside, filepath.Join(dir, "linked-secret.txt")); err != nil {
+		t.Fatalf("create symlink: %v", err)
+	}
+
+	buf, err := buildTemplateTar(dir)
+	if err != nil {
+		t.Fatalf("buildTemplateTar: %v", err)
+	}
+
+	names := map[string]string{}
+	tr := tar.NewReader(buf)
+	for {
+		hdr, err := tr.Next()
+		if errors.Is(err, io.EOF) {
+			break
+		}
+		if err != nil {
+			t.Fatalf("read tar: %v", err)
+		}
+		body, err := io.ReadAll(tr)
+		if err != nil {
+			t.Fatalf("read body for %s: %v", hdr.Name, err)
+		}
+		names[hdr.Name] = string(body)
+	}
+
+	if got := names["config.yaml"]; got != "name: safe\n" {
+		t.Fatalf("config.yaml body = %q, want safe config", got)
+	}
+	if _, ok := names["linked-secret.txt"]; ok {
+		t.Fatalf("symlink entry was copied into template tar: %#v", names)
+	}
+	for name, body := range names {
+		if strings.Contains(body, "do-not-copy") {
+			t.Fatalf("symlink target leaked through %s: %q", name, body)
+		}
+	}
+}
+
 // baseHostConfig returns a fresh HostConfig with typical pre-tier binds,
 // mimicking what Start() builds before calling ApplyTierConfig.
 func baseHostConfig(pluginsPath string) *container.HostConfig {
@@ -636,10 +704,15 @@ func TestBuildContainerEnv_AwarenessOnlyWhenBothSet(t *testing.T) {
 }
 
 func TestBuildContainerEnv_CustomEnvVarsAppended(t *testing.T) {
+	// NOTE: this test previously asserted GITHUB_TOKEN passed through
+	// verbatim. That assertion encoded the forensic #145 latent leak as
+	// expected behavior. Post-guard, ordinary custom env still flows but
+	// SCM-write credentials are stripped — see
+	// TestBuildContainerEnv_StripsSCMWriteTokens for the negative assertion.
 	cfg := WorkspaceConfig{
 		WorkspaceID: "ws-x",
 		PlatformURL: "http://localhost:8080",
-		EnvVars:     map[string]string{"CUSTOM": "value", "GITHUB_TOKEN": "fake-token-for-test"},
+		EnvVars:     map[string]string{"CUSTOM": "value", "ANTHROPIC_API_KEY": "sk-not-an-scm-token"},
 	}
 	env := buildContainerEnv(cfg)
 	seen := map[string]string{}
@@ -652,8 +725,8 @@ func TestBuildContainerEnv_CustomEnvVarsAppended(t *testing.T) {
 	if seen["CUSTOM"] != "value" {
 		t.Errorf("CUSTOM env missing, got env=%v", env)
 	}
-	if seen["GITHUB_TOKEN"] != "fake-token-for-test" {
-		t.Errorf("GITHUB_TOKEN env missing, got env=%v", env)
+	if seen["ANTHROPIC_API_KEY"] != "sk-not-an-scm-token" {
+		t.Errorf("non-SCM custom env must still pass through, got env=%v", env)
 	}
 	// Built-in defaults still present
 	if seen["MOLECULE_URL"] == "" {
@@ -661,6 +734,129 @@ func TestBuildContainerEnv_CustomEnvVarsAppended(t *testing.T) {
 	}
 }
 
+// ---------- forensic #145: SCM-write-token denylist guard ----------
+
+// TestBuildContainerEnv_StripsSCMWriteTokens is the core negative
+// assertion: a tenant workspace env constructed via buildContainerEnv MUST
+// NOT contain any Git SCM *write* credential, regardless of how it got into
+// cfg.EnvVars. This proves the two-eyes review gate stays structurally
+// self-bypass-proof — an agent in-container has no merge/approve token to
+// act on a forged approval. See forensic #145.
+//
+// This test FAILS on the pre-guard code (where buildContainerEnv passed
+// cfg.EnvVars through verbatim) and PASSES once the denylist filter is in
+// place — i.e. the guard is proven by construction, not by environment
+// accident.
+func TestBuildContainerEnv_StripsSCMWriteTokens(t *testing.T) {
+	scmTokens := []string{
+		"GITEA_TOKEN", "GITHUB_TOKEN", "GH_TOKEN",
+		"GITLAB_TOKEN", "GL_TOKEN", "BITBUCKET_TOKEN",
+	}
+
+	t.Run("normal path — SCM tokens explicitly set in EnvVars", func(t *testing.T) {
+		envVars := map[string]string{"CUSTOM": "ok", "ANTHROPIC_API_KEY": "sk-keep"}
+		for _, k := range scmTokens {
+			envVars[k] = "leaked-write-credential-" + k
+		}
+		cfg := WorkspaceConfig{
+			WorkspaceID: "ws-tenant",
+			PlatformURL: "http://localhost:8080",
+			Tier:        2,
+			EnvVars:     envVars,
+		}
+		assertNoSCMWriteToken(t, buildContainerEnv(cfg), scmTokens)
+
+		// Sanity: non-SCM custom env is NOT collateral-damaged by the filter.
+		if !envContains(buildContainerEnv(cfg), "CUSTOM=ok") {
+			t.Errorf("filter must not strip non-SCM custom env")
+		}
+		if !envContains(buildContainerEnv(cfg), "ANTHROPIC_API_KEY=sk-keep") {
+			t.Errorf("filter must not strip non-SCM API keys")
+		}
+	})
+
+	t.Run("persona-file path — simulates loadPersonaEnvFile merge", func(t *testing.T) {
+		// The latent path: handlers.loadPersonaEnvFile() merges a per-role
+		// persona env file (carrying GITEA_USER, GITEA_TOKEN, …) into the
+		// workspace env map when MOLECULE_PERSONA_ROOT is set on a tenant
+		// host. We can't invoke that cross-package helper here, but its
+		// observable effect is exactly "a GITEA_TOKEN appears in
+		// cfg.EnvVars". Constructing that condition directly proves the
+		// guard holds even if the latent path becomes reachable.
+		cfg := WorkspaceConfig{
+			WorkspaceID: "ws-tenant",
+			PlatformURL: "http://localhost:8080",
+			Tier:        2,
+			EnvVars: map[string]string{
+				// Persona identity fields that are SAFE to keep (read-only
+				// identity, not a write credential):
+				"GITEA_USER":       "backend-engineer",
+				"GITEA_USER_EMAIL": "backend-engineer@agents.moleculesai.app",
+				// The credential that must be stripped:
+				"GITEA_TOKEN":        "persona-merged-write-pat",
+				"GITEA_TOKEN_SCOPES": "write:repository",
+			},
+		}
+		got := buildContainerEnv(cfg)
+		assertNoSCMWriteToken(t, got, scmTokens)
+		// Non-credential persona identity may still flow through — only the
+		// write token is the denied surface.
+		if !envContains(got, "GITEA_USER=backend-engineer") {
+			t.Errorf("non-credential persona identity (GITEA_USER) should not be stripped")
+		}
+	})
+}
+
+// TestCPProvisionerEnv_StripsSCMWriteTokens covers the tenant-EC2 path:
+// CPProvisioner.Start builds the env map the control plane forwards to the
+// EC2 workspace container. The same forensic #145 denylist must hold there.
+func TestCPProvisionerEnv_StripsSCMWriteTokens(t *testing.T) {
+	// isSCMWriteTokenKey is the single source of truth shared by both
+	// buildContainerEnv (local Docker) and CPProvisioner.Start (tenant EC2).
+	// Assert it classifies every known SCM-write var as denied and leaves
+	// ordinary / read-only-identity vars alone.
+	for _, k := range []string{
+		"GITEA_TOKEN", "GITHUB_TOKEN", "GH_TOKEN",
+		"GITLAB_TOKEN", "GL_TOKEN", "BITBUCKET_TOKEN",
+	} {
+		if !isSCMWriteTokenKey(k) {
+			t.Errorf("isSCMWriteTokenKey(%q) = false, want true (SCM-write credential must be denied)", k)
+		}
+	}
+	for _, k := range []string{
+		"GITEA_USER", "GITEA_USER_EMAIL", "ANTHROPIC_API_KEY",
+		"CUSTOM", "PLATFORM_URL", "ADMIN_TOKEN", "",
+	} {
+		if isSCMWriteTokenKey(k) {
+			t.Errorf("isSCMWriteTokenKey(%q) = true, want false (must not over-strip non-SCM env)", k)
+		}
+	}
+}
+
+func assertNoSCMWriteToken(t *testing.T, env []string, scmTokens []string) {
+	t.Helper()
+	for _, e := range env {
+		key := e
+		if i := strings.IndexByte(e, '='); i >= 0 {
+			key = e[:i]
+		}
+		for _, banned := range scmTokens {
+			if key == banned {
+				t.Errorf("SCM-write credential %q leaked into workspace env (forensic #145 invariant violated): %q", banned, e)
+			}
+		}
+	}
+}
+
+func envContains(env []string, want string) bool {
+	for _, e := range env {
+		if e == want {
+			return true
+		}
+	}
+	return false
+}
+
 // ---------- buildWorkspaceMount — #65 workspace_access ----------
 
 func TestBuildWorkspaceMount_SelectionMatrix(t *testing.T) {

workspace-server/internal/registry/access_test.go

@@ -14,8 +14,9 @@ func setupMockDB(t *testing.T) sqlmock.Sqlmock {
 	if err != nil {
 		t.Fatalf("sqlmock: %v", err)
 	}
+	prevDB := db.DB
 	db.DB = mockDB
-	t.Cleanup(func() { mockDB.Close() })
+	t.Cleanup(func() { mockDB.Close(); db.DB = prevDB })
 	return mock
 }
 

workspace-server/internal/registry/healthsweep_test.go

@@ -31,8 +31,9 @@ func setupTestDB(t *testing.T) sqlmock.Sqlmock {
 	if err != nil {
 		t.Fatalf("failed to create sqlmock: %v", err)
 	}
+	prevDB := db.DB
 	db.DB = mockDB
-	t.Cleanup(func() { mockDB.Close() })
+	t.Cleanup(func() { mockDB.Close(); db.DB = prevDB })
 	return mock
 }
 

workspace-server/internal/registry/hibernation_test.go

@@ -17,8 +17,9 @@ func setupHibernationMock(t *testing.T) sqlmock.Sqlmock {
 	if err != nil {
 		t.Fatalf("sqlmock.New: %v", err)
 	}
+	prevDB := db.DB
 	db.DB = mockDB
-	t.Cleanup(func() { mockDB.Close() })
+	t.Cleanup(func() { mockDB.Close(); db.DB = prevDB })
 	return mock
 }
 

workspace-server/internal/registry/liveness_test.go

@@ -18,8 +18,9 @@ func setupLivenessTestDB(t *testing.T) sqlmock.Sqlmock {
 	if err != nil {
 		t.Fatalf("failed to create sqlmock: %v", err)
 	}
+	prevDB := db.DB
 	db.DB = mockDB
-	t.Cleanup(func() { mockDB.Close() })
+	t.Cleanup(func() { mockDB.Close(); db.DB = prevDB })
 	return mock
 }
 

workspace-server/internal/scheduler/scheduler_test.go

@@ -24,8 +24,9 @@ func setupTestDB(t *testing.T) sqlmock.Sqlmock {
 	if err != nil {
 		t.Fatalf("failed to create sqlmock: %v", err)
 	}
+	prevDB := db.DB
 	db.DB = mockDB
-	t.Cleanup(func() { mockDB.Close() })
+	t.Cleanup(func() { mockDB.Close(); db.DB = prevDB })
 	return mock
 }
 

workspace-server/internal/secrets/patterns.go

@@ -0,0 +1,226 @@
+// Package secrets provides the canonical SSOT for credential-shaped
+// regex patterns used by:
+//
+//   - the CI `Secret scan` workflow (.gitea/workflows/secret-scan.yml)
+//   - the runtime's bundled pre-commit hook
+//     (molecule-ai-workspace-runtime/molecule_runtime/scripts/pre-commit-checks.sh)
+//   - the upcoming Phase 2b docker-exec Files API backend, which has
+//     to refuse to surface files whose path OR content matches a
+//     credential shape (RFC internal#425, Hongming 2026-05-15)
+//
+// Before this package, the same regex set lived as duplicate bash
+// arrays in two unrelated repos; adding a pattern required editing
+// both, and pattern drift was caught only via secret-scan workflow
+// failures on PRs that had unrelated changes (#2090-class incident
+// vector). Centralising in Go makes the Files API the SSOT, with the
+// YAML + bash arrays generated/asserted from this package so drift
+// is detected at CI time, not at exfiltration time.
+//
+// This file is Phase 2a of the internal#425 RFC. Phase 2b will import
+// `Patterns` from `template_files_docker_exec.go` to gate
+// `listFilesViaDockerExec` / `readFileViaDockerExec` against
+// secret-shaped paths AND content. Until 2b lands, the package has
+// one consumer: this package's own unit tests, which pin the regex
+// strings so a refactor that drops or weakens one is caught here.
+package secrets
+
+import (
+	"fmt"
+	"regexp"
+	"sync"
+)
+
+// Pattern is one named credential shape — a human label plus the
+// compiled regex. The label appears in CI error output ("matched:
+// github-pat") so an operator can identify the family without seeing
+// the actual matched bytes (echoing the bytes widens the blast radius
+// per the secret-scan workflow's recovery prose).
+type Pattern struct {
+	// Name is a short kebab-case identifier (e.g. "github-pat",
+	// "anthropic-api-key"). Stable across versions — consumers may
+	// switch on it.
+	Name string
+	// Description is a one-line human-readable explanation of what
+	// the pattern matches. Used in CI error messages and the Files
+	// API "<denied: secret-shape>" placeholder rationale.
+	Description string
+	// regexSource is the regex literal in Go-RE2 syntax. Stored as a
+	// string so the slice declaration below stays readable; compiled
+	// once via sync.Once into a *regexp.Regexp.
+	regexSource string
+}
+
+// Patterns is the canonical credential-shape regex set.
+//
+// Adding a pattern here:
+//
+//  1. Add a new Pattern{} entry below with a kebab-case Name, a
+//     one-line Description, and the regex literal. Anchor on a
+//     low-false-positive prefix.
+//  2. Add a positive + negative test case in patterns_test.go.
+//  3. Mirror the regex string into:
+//     a. .gitea/workflows/secret-scan.yml SECRET_PATTERNS array
+//     b. molecule-ai-workspace-runtime/molecule_runtime/scripts/pre-commit-checks.sh
+//     (or wait for the codegen target that consumes this slice — TBD
+//     follow-up; tracked in the Phase 2a PR description.)
+//
+// The order is: alphabetical within each provider family, families
+// grouped by ecosystem (GitHub family, AI-provider family, chat
+// family, cloud family). Keep this stable so diffs are reviewable.
+var Patterns = []Pattern{
+	// --- GitHub token family ---
+	{
+		Name:        "github-pat-classic",
+		Description: "GitHub personal access token (classic)",
+		regexSource: `ghp_[A-Za-z0-9]{36,}`,
+	},
+	{
+		Name:        "github-app-installation-token",
+		Description: "GitHub App installation token (#2090 vector)",
+		regexSource: `ghs_[A-Za-z0-9]{36,}`,
+	},
+	{
+		Name:        "github-oauth-user-to-server",
+		Description: "GitHub OAuth user-to-server token",
+		regexSource: `gho_[A-Za-z0-9]{36,}`,
+	},
+	{
+		Name:        "github-oauth-user",
+		Description: "GitHub OAuth user token",
+		regexSource: `ghu_[A-Za-z0-9]{36,}`,
+	},
+	{
+		Name:        "github-oauth-refresh",
+		Description: "GitHub OAuth refresh token",
+		regexSource: `ghr_[A-Za-z0-9]{36,}`,
+	},
+	{
+		Name:        "github-pat-fine-grained",
+		Description: "GitHub fine-grained personal access token",
+		regexSource: `github_pat_[A-Za-z0-9_]{82,}`,
+	},
+
+	// --- AI-provider API key family ---
+	{
+		Name:        "anthropic-api-key",
+		Description: "Anthropic API key",
+		regexSource: `sk-ant-[A-Za-z0-9_-]{40,}`,
+	},
+	{
+		Name:        "openai-project-key",
+		Description: "OpenAI project API key",
+		regexSource: `sk-proj-[A-Za-z0-9_-]{40,}`,
+	},
+	{
+		Name:        "openai-service-account-key",
+		Description: "OpenAI service-account API key",
+		regexSource: `sk-svcacct-[A-Za-z0-9_-]{40,}`,
+	},
+	{
+		Name:        "minimax-api-key",
+		Description: "MiniMax API key (F1088 vector)",
+		regexSource: `sk-cp-[A-Za-z0-9_-]{60,}`,
+	},
+
+	// --- Chat-platform token family ---
+	{
+		Name:        "slack-token",
+		Description: "Slack token (xoxb/xoxa/xoxp/xoxr/xoxs)",
+		regexSource: `xox[baprs]-[A-Za-z0-9-]{20,}`,
+	},
+
+	// --- Cloud-provider credential family ---
+	{
+		Name:        "aws-access-key-id",
+		Description: "AWS access key ID",
+		regexSource: `AKIA[0-9A-Z]{16}`,
+	},
+	{
+		Name:        "aws-sts-temp-access-key-id",
+		Description: "AWS STS temporary access key ID",
+		regexSource: `ASIA[0-9A-Z]{16}`,
+	},
+}
+
+// compiledOnce protects the lazy build of compiledPatterns. We compile
+// lazily so package init is cheap; callers pay only on first match
+// (typically once per workspace-server boot).
+var (
+	compiledOnce     sync.Once
+	compiledPatterns []*compiledPattern
+	compileErr       error
+)
+
+type compiledPattern struct {
+	Name        string
+	Description string
+	Re          *regexp.Regexp
+}
+
+// compileAll compiles every Pattern.regexSource into a *regexp.Regexp.
+// Called once via compiledOnce. Any compile failure here is a build
+// bug (the unit tests assert each regex compiles) — surfacing via
+// returned error so callers don't panic in request handling.
+func compileAll() {
+	out := make([]*compiledPattern, 0, len(Patterns))
+	for _, p := range Patterns {
+		re, err := regexp.Compile(p.regexSource)
+		if err != nil {
+			compileErr = fmt.Errorf("secrets: pattern %q failed to compile: %w", p.Name, err)
+			return
+		}
+		out = append(out, &compiledPattern{Name: p.Name, Description: p.Description, Re: re})
+	}
+	compiledPatterns = out
+}
+
+// ScanBytes returns a non-nil Match if any pattern matches anywhere
+// inside b. Returns (nil, nil) on no match. Returns (nil, err) only
+// if a regex in the package fails to compile — that's a build bug,
+// not a runtime data issue.
+//
+// Match contains the pattern Name + Description so the caller can
+// emit a path-or-content-denial rationale WITHOUT round-tripping the
+// matched bytes (which would defeat the purpose). The matched bytes
+// stay inside this function.
+//
+// The Files API Phase 2b backend will call ScanBytes on:
+//
+//   - the absolute path string (catches a file literally named
+//     `ghs_abc.txt`)
+//   - the file content (catches a credential pasted into a workspace
+//     file by an agent or user — the Files API refuses to surface it
+//     and the canvas renders "<denied: secret-shape>")
+//
+// Ordering: patterns are tried in declaration order. First match
+// wins. This means narrower patterns (e.g. `sk-svcacct-…`) should
+// appear in `Patterns` before broader ones (`sk-…`) — today there's
+// no overlap, so order is descriptive only.
+func ScanBytes(b []byte) (*Match, error) {
+	compiledOnce.Do(compileAll)
+	if compileErr != nil {
+		return nil, compileErr
+	}
+	for _, cp := range compiledPatterns {
+		if cp.Re.Match(b) {
+			return &Match{Name: cp.Name, Description: cp.Description}, nil
+		}
+	}
+	return nil, nil
+}
+
+// ScanString is the string-input convenience wrapper around ScanBytes.
+// Identical semantics — the body never copies, []byte(s) is a
+// zero-copy reinterpret for the regex matcher.
+func ScanString(s string) (*Match, error) {
+	return ScanBytes([]byte(s))
+}
+
+// Match describes which pattern caught a value. Deliberately does
+// NOT include the matched substring — callers must not echo it.
+type Match struct {
+	// Name is the pattern's kebab-case identifier (e.g. "github-pat-classic").
+	Name string
+	// Description is the human-readable line for UI / log surfaces.
+	Description string
+}

workspace-server/internal/secrets/patterns_test.go

@@ -0,0 +1,189 @@
+package secrets
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestEveryPatternCompiles pins that every Pattern.regexSource is a
+// valid Go-RE2 expression. Without this, a bad regex would silently
+// disable ScanBytes for everything after it (the lazy compile would
+// set compileErr and ScanBytes would return that error every call).
+func TestEveryPatternCompiles(t *testing.T) {
+	for _, p := range Patterns {
+		if p.Name == "" {
+			t.Errorf("pattern with empty Name: regex=%q", p.regexSource)
+		}
+		if p.Description == "" {
+			t.Errorf("pattern %q has empty Description", p.Name)
+		}
+	}
+	// Force compile + check error.
+	if _, err := ScanBytes([]byte("placeholder")); err != nil {
+		t.Fatalf("ScanBytes init failed: %v", err)
+	}
+}
+
+// TestNoDuplicateNames — a duplicate pattern Name would make the
+// "first match wins" semantics surprising to readers and any caller
+// switching on Match.Name (none today but adding the guard is cheap).
+func TestNoDuplicateNames(t *testing.T) {
+	seen := map[string]bool{}
+	for _, p := range Patterns {
+		if seen[p.Name] {
+			t.Errorf("duplicate pattern Name: %q", p.Name)
+		}
+		seen[p.Name] = true
+	}
+}
+
+// TestKnownPatternsAllPresent — pins which specific Name values are
+// expected. A future refactor that renames or removes one without
+// updating consumers (CI workflow, runtime pre-commit hook, Files
+// API Phase 2b backend) would silently widen the leak surface.
+// Failing here forces the rename to be intentional.
+func TestKnownPatternsAllPresent(t *testing.T) {
+	expected := []string{
+		"github-pat-classic",
+		"github-app-installation-token",
+		"github-oauth-user-to-server",
+		"github-oauth-user",
+		"github-oauth-refresh",
+		"github-pat-fine-grained",
+		"anthropic-api-key",
+		"openai-project-key",
+		"openai-service-account-key",
+		"minimax-api-key",
+		"slack-token",
+		"aws-access-key-id",
+		"aws-sts-temp-access-key-id",
+	}
+	got := map[string]bool{}
+	for _, p := range Patterns {
+		got[p.Name] = true
+	}
+	for _, want := range expected {
+		if !got[want] {
+			t.Errorf("expected pattern %q missing from Patterns slice", want)
+		}
+	}
+}
+
+// TestPositiveMatches — for each pattern, supply a representative
+// shape and assert ScanBytes returns a Match with the right Name.
+// These are TEST FIXTURES, not real credentials — each is the
+// pattern's prefix + a long-enough trailing run of placeholder chars.
+// `EXAMPLE` is sprinkled in to make grep-finds in CI logs obviously
+// fake to a human reader (matches saved memory
+// feedback_assert_exact_not_substring: tighten by Name not body).
+func TestPositiveMatches(t *testing.T) {
+	cases := []struct {
+		fixture      string
+		expectedName string
+	}{
+		{"ghp_EXAMPLE111122223333444455556666777788889999", "github-pat-classic"},
+		{"ghs_EXAMPLE111122223333444455556666777788889999", "github-app-installation-token"},
+		{"gho_EXAMPLE111122223333444455556666777788889999", "github-oauth-user-to-server"},
+		{"ghu_EXAMPLE111122223333444455556666777788889999", "github-oauth-user"},
+		{"ghr_EXAMPLE111122223333444455556666777788889999", "github-oauth-refresh"},
+		{"github_pat_EXAMPLE" + strings.Repeat("1", 80), "github-pat-fine-grained"},
+		{"sk-ant-EXAMPLE" + strings.Repeat("1", 40), "anthropic-api-key"},
+		{"sk-proj-EXAMPLE" + strings.Repeat("1", 40), "openai-project-key"},
+		{"sk-svcacct-EXAMPLE" + strings.Repeat("1", 40), "openai-service-account-key"},
+		{"sk-cp-EXAMPLE" + strings.Repeat("1", 60), "minimax-api-key"},
+		{"xoxb-" + strings.Repeat("a", 25), "slack-token"},
+		{"xoxa-" + strings.Repeat("a", 25), "slack-token"},
+		// AWS regex requires [0-9A-Z]{16} — uppercase + digits only.
+		{"AKIA1234567890ABCDEF", "aws-access-key-id"},
+		{"ASIA1234567890ABCDEF", "aws-sts-temp-access-key-id"},
+	}
+	for _, tc := range cases {
+		t.Run(tc.expectedName, func(t *testing.T) {
+			m, err := ScanBytes([]byte(tc.fixture))
+			if err != nil {
+				t.Fatalf("ScanBytes(%q) errored: %v", tc.fixture, err)
+			}
+			if m == nil {
+				t.Fatalf("ScanBytes(%q) returned no match — expected %q", tc.fixture, tc.expectedName)
+			}
+			if m.Name != tc.expectedName {
+				t.Errorf("ScanBytes(%q) matched %q; expected %q", tc.fixture, m.Name, tc.expectedName)
+			}
+		})
+	}
+}
+
+// TestNegativeShapes — strings that look credential-adjacent but
+// shouldn't match (too short, wrong prefix, missing trailing bytes).
+// Failing here means a pattern is too loose, which would generate
+// false-positive denial in Files API and false-positive workflow
+// failures in CI.
+func TestNegativeShapes(t *testing.T) {
+	cases := []string{
+		// Too-short variants — anchored on the length suffix.
+		"ghp_tooshort",
+		"ghs_alsoshort1234",
+		"github_pat_short",
+		"sk-ant-short",
+		"sk-cp-not-enough-bytes-here",
+		// Looks like one of the prefixes but isn't (different letter).
+		"gha_EXAMPLE_thirty_six_or_more_chars_here_xxx",
+		// Slack family — wrong letter after xox.
+		"xoxz-aaaaaaaaaaaaaaaaaaaaaaaaa",
+		// AWS-shaped but wrong length suffix.
+		"AKIATOOSHORT",
+		// Empty / whitespace.
+		"",
+		"   ",
+		// Plain prose mentioning the prefix as part of a longer word.
+		"see also `ghp_HOWTO.md` in the repo",
+	}
+	for _, c := range cases {
+		t.Run(c, func(t *testing.T) {
+			m, err := ScanBytes([]byte(c))
+			if err != nil {
+				t.Fatalf("ScanBytes(%q) errored: %v", c, err)
+			}
+			if m != nil {
+				t.Errorf("ScanBytes(%q) unexpectedly matched %q", c, m.Name)
+			}
+		})
+	}
+}
+
+// TestScanString_NoOp — sanity-check ScanString is the zero-copy
+// wrapper around ScanBytes. Without this, a future refactor that
+// makes ScanString do its own thing (e.g. accidentally normalise
+// case) would diverge silently.
+func TestScanString_NoOp(t *testing.T) {
+	in := "ghp_EXAMPLE111122223333444455556666777788889999"
+	m1, err1 := ScanBytes([]byte(in))
+	if err1 != nil {
+		t.Fatalf("ScanBytes errored: %v", err1)
+	}
+	m2, err2 := ScanString(in)
+	if err2 != nil {
+		t.Fatalf("ScanString errored: %v", err2)
+	}
+	if m1 == nil || m2 == nil {
+		t.Fatalf("expected matches; got bytes=%+v string=%+v", m1, m2)
+	}
+	if m1.Name != m2.Name {
+		t.Errorf("ScanString and ScanBytes returned different Names: %q vs %q", m1.Name, m2.Name)
+	}
+}
+
+// TestMatch_NoRoundtrip — assert the Match struct does NOT include
+// the matched substring as a field. Adding such a field would
+// regress the "matched bytes never leave ScanBytes" invariant that
+// makes this package safe to call from log/UI surfaces. This is a
+// reflection-light contract test — checks the field names statically.
+func TestMatch_NoRoundtrip(t *testing.T) {
+	var m Match
+	// If someone adds a `Matched string` (or similar) field, this
+	// test reads as the canonical place to update + reconsider.
+	_ = m.Name
+	_ = m.Description
+	// The two-field shape is part of the public contract; new fields
+	// require deliberation about whether they leak the secret value.
+}

workspace/a2a_mcp_server.py

@@ -35,12 +35,14 @@ from a2a_tools import (
     tool_commit_memory,
     tool_delegate_task,
     tool_delegate_task_async,
+    tool_get_runtime_identity,
     tool_get_workspace_info,
     tool_inbox_peek,
     tool_inbox_pop,
     tool_list_peers,
     tool_recall_memory,
     tool_send_message_to_user,
+    tool_update_agent_card,
     tool_wait_for_message,
 )
 from platform_tools.registry import TOOLS as _PLATFORM_TOOL_SPECS
@@ -130,6 +132,10 @@ async def handle_tool_call(name: str, arguments: dict) -> str:
         return await tool_get_workspace_info(
             source_workspace_id=arguments.get("source_workspace_id") or None,
         )
+    elif name == "get_runtime_identity":
+        return await tool_get_runtime_identity()
+    elif name == "update_agent_card":
+        return await tool_update_agent_card(arguments.get("card"))
     elif name == "commit_memory":
         return await tool_commit_memory(
             arguments.get("content", ""),
@@ -692,8 +698,8 @@ def _format_channel_content(
 # --- MCP Server (JSON-RPC over stdio) ---
 
 
-def _warn_if_stdio_not_pipe(stdin_fd: int = 0, stdout_fd: int = 1) -> None:
-    """Warn when stdio isn't a pipe — but continue anyway.
+def _assert_stdio_is_pipe_compatible(stdin_fd: int = 0, stdout_fd: int = 1) -> None:
+    """Assert that stdio fds are pipe/socket/char-device compatible.
 
     The legacy asyncio.connect_read_pipe / connect_write_pipe transport
     rejected regular files, PTYs, and sockets with:
@@ -717,6 +723,10 @@ def _warn_if_stdio_not_pipe(stdin_fd: int = 0, stdout_fd: int = 1) -> None:
             )
 
 
+# Deprecated alias — the canonical name is _assert_stdio_is_pipe_compatible.
+_warn_if_stdio_not_pipe = _assert_stdio_is_pipe_compatible
+
+
 async def main():  # pragma: no cover
     """Run MCP server on stdio — reads JSON-RPC requests, writes responses.
 
@@ -973,7 +983,7 @@ def cli_main(transport: str = "stdio", port: int = 9100) -> None:  # pragma: no
     if transport == "http":
         asyncio.run(_run_http_server(port))
     else:
-        _warn_if_stdio_not_pipe()
+        _assert_stdio_is_pipe_compatible()
         asyncio.run(main())
 
 

workspace/a2a_tools.py

@@ -167,3 +167,15 @@ from a2a_tools_inbox import (  # noqa: E402  (import after the top-of-module imp
     tool_inbox_pop,
     tool_wait_for_message,
 )
+
+
+# Identity tool handlers — extracted to a2a_tools_identity. Ports the
+# two T4-tier MCP tools (``tool_get_runtime_identity`` +
+# ``tool_update_agent_card``) from molecule-ai-workspace-runtime PR#17.
+# That repo is mirror-only (reference_runtime_repo_is_mirror_only);
+# this is the canonical edit point, and the wheel mirror is
+# regenerated by publish-runtime.yml on merge.
+from a2a_tools_identity import (  # noqa: E402  (import after the top-of-module imports)
+    tool_get_runtime_identity,
+    tool_update_agent_card,
+)

workspace/a2a_tools_identity.py

@@ -0,0 +1,187 @@
+"""Identity tool handlers — single-concern slice of the a2a_tools surface.
+
+Owns the two MCP tools that close the T4-tier workspace owner-permission
+gaps reported via the canvas:
+
+  * ``tool_get_runtime_identity`` — env-only; returns model, model_provider,
+    molecule_model, anthropic_base_url, tier, workspace_id, runtime
+    (ADAPTER_MODULE). No HTTP call. Always permitted by RBAC — even
+    read-only agents may know what model they are.
+
+  * ``tool_update_agent_card`` — POSTs the card to ``/registry/update-card``
+    with the workspace's own bearer (same auth path as ``tool_commit_memory``
+    via ``a2a_tools_rbac.auth_headers_for_heartbeat``). The platform
+    replaces the stored card and broadcasts an ``agent_card_updated``
+    event so the canvas reflects the new card live. Gated on
+    ``memory.write`` capability via the existing RBAC permission map so
+    read-only roles can't silently rewrite the platform card.
+
+Both originated as a port of molecule-ai-workspace-runtime PR#17
+(``feat(mcp): add update_agent_card + get_runtime_identity tools``).
+The mirror-only PR#17 was closed without merge per
+``reference_runtime_repo_is_mirror_only``; the canonical edit point is
+this monorepo at ``workspace/`` and the wheel mirror is regenerated
+automatically by the publish-runtime workflow.
+
+Imports the auth-header primitive from ``a2a_tools_rbac`` (iter 4a) —
+NOT from ``a2a_tools`` — to avoid a circular import with the
+kitchen-sink re-export module.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+import httpx
+
+from a2a_client import PLATFORM_URL
+from a2a_tools_rbac import (
+    auth_headers_for_heartbeat as _auth_headers_for_heartbeat,
+    check_memory_write_permission as _check_memory_write_permission,
+)
+
+
+def _runtime_identity_payload() -> dict[str, Any]:
+    """Build the identity dict — env-only, no I/O.
+
+    Factored out from ``tool_get_runtime_identity`` so tests can assert
+    against the exact key set without re-parsing JSON. The MCP tool
+    handler ``tool_get_runtime_identity`` is the only public caller in
+    production; tests call this helper directly.
+    """
+    return {
+        "model": os.environ.get("MODEL", ""),
+        "model_provider": os.environ.get("MODEL_PROVIDER", ""),
+        "molecule_model": os.environ.get("MOLECULE_MODEL", ""),
+        "anthropic_base_url": os.environ.get("ANTHROPIC_BASE_URL", ""),
+        "tier": os.environ.get("TIER", ""),
+        "workspace_id": os.environ.get("WORKSPACE_ID", ""),
+        # Adapter module is the closest thing the runtime has to a
+        # "template slug" — e.g. "adapter" for claude-code-default,
+        # "hermes" for hermes-template, etc. Picked from
+        # $ADAPTER_MODULE env baked by each template's Dockerfile.
+        "runtime": os.environ.get("ADAPTER_MODULE", ""),
+    }
+
+
+async def tool_get_runtime_identity() -> str:
+    """Return this runtime's identity — model, provider, tier, IDs.
+
+    Env-only; no HTTP call. Useful so the agent can answer "what model
+    am I?" correctly instead of guessing from a stale system prompt
+    that the operator may have changed between boots.
+
+    Returns the identity as a JSON-encoded string (the dispatch contract
+    every MCP tool in this module follows). Tests that want to assert
+    individual fields can call ``_runtime_identity_payload()`` directly,
+    or ``json.loads`` the return value.
+
+    Always permitted by RBAC — there is no sensitive information here
+    that isn't already available to the process via ``os.environ``.
+    The point of the tool is to surface those env values to the agent
+    layer in a stable, documented shape rather than expecting every
+    agent runtime to know to ``echo $MODEL``.
+    """
+    return json.dumps(_runtime_identity_payload(), indent=2)
+
+
+async def tool_update_agent_card(card: Any) -> str:
+    """Update this workspace's agent_card on the platform.
+
+    POSTs the provided card to ``/registry/update-card`` with the
+    workspace's own bearer token (same auth path as ``tool_commit_memory``
+    and ``tool_get_workspace_info``). The platform validates required
+    fields server-side, replaces the stored card, and broadcasts an
+    ``agent_card_updated`` event so the canvas updates live.
+
+    Args:
+        card: A JSON-serialisable object (typically a dict) holding the
+            new card. The platform validates required fields server-side.
+
+    Returns:
+        JSON-encoded string. Body:
+          - ``{"success": true, "status": "updated"}`` on success;
+          - ``{"success": false, "error": "<msg>", "status_code": <int>}``
+            on platform error;
+          - ``{"success": false, "error": "<reason>"}`` on local validation
+            (non-dict card, missing WORKSPACE_ID, network error).
+
+    Permission gate: this tool requires the ``memory.write`` RBAC
+    capability — same gate as ``tool_commit_memory``. The check runs
+    inline rather than at the dispatcher layer to keep ``a2a_mcp_server``
+    permission-agnostic (the gate sits with the implementation, not the
+    transport). Read-only roles get a clear error string back instead
+    of a 403 from the platform.
+
+    We re-check ``isinstance(card, dict)`` here defensively rather than
+    trust the MCP schema validator alone — the schema only constrains
+    the transport, not the in-process call surface used by tests and
+    sibling modules.
+    """
+    payload = await _update_agent_card_impl(card)
+    return json.dumps(payload, indent=2)
+
+
+async def _update_agent_card_impl(card: Any) -> dict[str, Any]:
+    """Dict-returning core of ``tool_update_agent_card``.
+
+    Split out so tests can assert against the raw dict shape (status
+    codes, error messages) without re-parsing JSON on every assertion.
+    The string-returning ``tool_update_agent_card`` is a thin wrapper
+    invoked by the MCP dispatcher.
+    """
+    # RBAC: require memory.write permission. Same gate as
+    # tool_commit_memory (the agent already needs this capability to
+    # persist anything outbound). Read-only roles can still call
+    # get_runtime_identity / get_workspace_info to introspect — those
+    # are env-only / read-only and have no inline gate.
+    if not _check_memory_write_permission():
+        return {
+            "success": False,
+            "error": (
+                "RBAC — this workspace does not have the 'memory.write' "
+                "permission required to update the agent_card."
+            ),
+        }
+    if not isinstance(card, dict):
+        return {
+            "success": False,
+            "error": "card must be a JSON object (dict)",
+        }
+    ws_id = os.environ.get("WORKSPACE_ID", "")
+    if not ws_id:
+        return {
+            "success": False,
+            "error": "WORKSPACE_ID env not set; cannot identify caller",
+        }
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            resp = await client.post(
+                f"{PLATFORM_URL}/registry/update-card",
+                json={"workspace_id": ws_id, "agent_card": card},
+                headers=_auth_headers_for_heartbeat(),
+            )
+            if resp.status_code == 200:
+                body: dict[str, Any] = {}
+                try:
+                    body = resp.json()
+                except Exception:
+                    pass
+                return {
+                    "success": True,
+                    "status": body.get("status", "updated"),
+                }
+            # Non-200 — surface what the platform returned.
+            error_msg = ""
+            try:
+                error_msg = resp.json().get("error", "") or resp.text
+            except Exception:
+                error_msg = resp.text
+            return {
+                "success": False,
+                "status_code": resp.status_code,
+                "error": error_msg,
+            }
+    except Exception as e:
+        return {"success": False, "error": f"network error: {e}"}

workspace/executor_helpers.py

@@ -340,6 +340,16 @@ _CLI_A2A_COMMAND_KEYWORDS: dict[str, str | None] = {
     "delegate_task_async": "delegate --async",
     "check_task_status": "status",
     "get_workspace_info": "info",
+    # `get_runtime_identity` + `update_agent_card` are MCP-first
+    # capabilities — the CLI subprocess interface doesn't expose them
+    # today. `get_runtime_identity` is env-only and an agent on a
+    # CLI-only runtime can already `echo $MODEL` etc, so there's no
+    # functional gap. `update_agent_card` requires a JSON object
+    # argument that wouldn't survive a positional-arg shell invocation
+    # cleanly. Mapped to None — flip to a keyword if a2a_cli grows
+    # `identity` / `card` subcommands in the future.
+    "get_runtime_identity": None,
+    "update_agent_card": None,
     # `broadcast_message` is not exposed via the CLI subprocess interface
     # today — it's an MCP-first capability. If a2a_cli grows a `broadcast`
     # subcommand, map it here and the alignment test will gate the change.

workspace/platform_tools/registry.py

@@ -57,12 +57,14 @@ from a2a_tools import (
     tool_commit_memory,
     tool_delegate_task,
     tool_delegate_task_async,
+    tool_get_runtime_identity,
     tool_get_workspace_info,
     tool_inbox_peek,
     tool_inbox_pop,
     tool_list_peers,
     tool_recall_memory,
     tool_send_message_to_user,
+    tool_update_agent_card,
     tool_wait_for_message,
 )
 
@@ -289,6 +291,61 @@ _GET_WORKSPACE_INFO = ToolSpec(
     section=A2A_SECTION,
 )
 
+_GET_RUNTIME_IDENTITY = ToolSpec(
+    name="get_runtime_identity",
+    short=(
+        "Return this runtime's identity — model, model_provider, tier, "
+        "workspace_id, runtime template. Reads from process env; no HTTP call."
+    ),
+    when_to_use=(
+        "Use this to answer 'what model am I?' truthfully instead of "
+        "guessing from a stale system prompt — the operator may have "
+        "routed you to a different model via persona env between boots. "
+        "Always permitted by RBAC: even read-only agents may know what "
+        "model they are. Distinct from get_workspace_info — that one "
+        "calls the platform for ID/role/tier/parent (workspace metadata); "
+        "this one returns the live process env (MODEL, MODEL_PROVIDER, "
+        "MOLECULE_MODEL, ANTHROPIC_BASE_URL, TIER, WORKSPACE_ID, "
+        "ADAPTER_MODULE)."
+    ),
+    input_schema={"type": "object", "properties": {}},
+    impl=tool_get_runtime_identity,
+    section=A2A_SECTION,
+)
+
+_UPDATE_AGENT_CARD = ToolSpec(
+    name="update_agent_card",
+    short=(
+        "Replace this workspace's agent_card on the platform. The "
+        "platform validates required fields and broadcasts an "
+        "agent_card_updated event so the canvas reflects the change live."
+    ),
+    when_to_use=(
+        "Use when the workspace's capabilities, skills, description, or "
+        "name change and the canvas display needs to follow. The "
+        "platform stores the new card and pushes an "
+        "``agent_card_updated`` event to subscribers. Gated behind the "
+        "``memory.write`` RBAC capability — read-only roles cannot "
+        "rewrite the card. Tier-1+ owners always have this capability."
+    ),
+    input_schema={
+        "type": "object",
+        "properties": {
+            "card": {
+                "type": "object",
+                "description": (
+                    "The new agent_card object (name, version, "
+                    "description, skills, etc). Server-side validation "
+                    "rejects payloads missing required fields."
+                ),
+            },
+        },
+        "required": ["card"],
+    },
+    impl=tool_update_agent_card,
+    section=A2A_SECTION,
+)
+
 _BROADCAST_MESSAGE = ToolSpec(
     name="broadcast_message",
     short=(
@@ -642,6 +699,8 @@ TOOLS: list[ToolSpec] = [
     _CHECK_TASK_STATUS,
     _LIST_PEERS,
     _GET_WORKSPACE_INFO,
+    _GET_RUNTIME_IDENTITY,
+    _UPDATE_AGENT_CARD,
     _BROADCAST_MESSAGE,
     _SEND_MESSAGE_TO_USER,
     # Inbox (standalone-only; in-container returns informational error)

workspace/tests/snapshots/a2a_instructions_mcp.txt

@@ -5,6 +5,8 @@
 - **check_task_status**: Poll the status of a task started with delegate_task_async; returns result when done.
 - **list_peers**: List the workspaces this agent can communicate with — name, ID, status, role for each.
 - **get_workspace_info**: Get this workspace's own info — ID, name, role, tier, parent, status.
+- **get_runtime_identity**: Return this runtime's identity — model, model_provider, tier, workspace_id, runtime template. Reads from process env; no HTTP call.
+- **update_agent_card**: Replace this workspace's agent_card on the platform. The platform validates required fields and broadcasts an agent_card_updated event so the canvas reflects the change live.
 - **broadcast_message**: Send a message to ALL agent workspaces in the org simultaneously. Requires broadcast_enabled=true on this workspace (set by user/admin).
 - **send_message_to_user**: Send a message directly to the user's canvas chat — pushed instantly via WebSocket. Use this to: (1) acknowledge a task immediately ('Got it, I'll start working on this'), (2) send interim progress updates while doing long work, (3) deliver follow-up results after delegation completes, (4) attach files (zip, pdf, csv, image) for the user to download via the `attachments` field (NEVER paste file URLs in `message`). The message appears in the user's chat as if you're proactively reaching out.
 - **wait_for_message**: Block until the next inbound message (canvas user OR peer agent) arrives, or until ``timeout_secs`` elapses.
@@ -27,6 +29,12 @@ Call this first when you need to delegate but don't know the target's ID. Access
 ### get_workspace_info
 Use to introspect your own identity (e.g. before reporting back to the user, or to determine whether you're a tier-0 root that can write GLOBAL memory).
 
+### get_runtime_identity
+Use this to answer 'what model am I?' truthfully instead of guessing from a stale system prompt — the operator may have routed you to a different model via persona env between boots. Always permitted by RBAC: even read-only agents may know what model they are. Distinct from get_workspace_info — that one calls the platform for ID/role/tier/parent (workspace metadata); this one returns the live process env (MODEL, MODEL_PROVIDER, MOLECULE_MODEL, ANTHROPIC_BASE_URL, TIER, WORKSPACE_ID, ADAPTER_MODULE).
+
+### update_agent_card
+Use when the workspace's capabilities, skills, description, or name change and the canvas display needs to follow. The platform stores the new card and pushes an ``agent_card_updated`` event to subscribers. Gated behind the ``memory.write`` RBAC capability — read-only roles cannot rewrite the card. Tier-1+ owners always have this capability.
+
 ### broadcast_message
 Use for urgent, org-wide signals: critical status changes, emergency stop instructions, coordinated task announcements. Every non-removed workspace receives the message in its activity log (poll-mode agents see it on their next poll; push-mode canvases get a real-time banner). This tool returns an error if broadcast_enabled is false — a user or admin must enable it via the workspace abilities settings first.
 

workspace/tests/test_a2a_mcp_server.py

@@ -1826,8 +1826,8 @@ def test_inbox_bridge_swallows_closed_loop_runtime_error():
 
 
 class TestStdioPipeAssertion:
-    """Pin _warn_if_stdio_not_pipe — the diagnostic warning that replaces
-    the old fatal _assert_stdio_is_pipe_compatible guard.
+    """Pin _assert_stdio_is_pipe_compatible — the canonical function name.
+    _warn_if_stdio_not_pipe is a deprecated alias.
 
     The universal stdio transport now works with ANY file descriptor
     (pipes, regular files, PTYs, sockets), so the old exit-2 behavior
@@ -1838,12 +1838,12 @@ class TestStdioPipeAssertion:
 
     def test_pipe_pair_passes_silently(self, caplog):
         """Happy path — both fds are pipes. No warning emitted."""
-        from a2a_mcp_server import _warn_if_stdio_not_pipe
+        from a2a_mcp_server import _assert_stdio_is_pipe_compatible
 
         r, w = os.pipe()
         try:
             with caplog.at_level("WARNING"):
-                _warn_if_stdio_not_pipe(stdin_fd=r, stdout_fd=w)
+                _assert_stdio_is_pipe_compatible(stdin_fd=r, stdout_fd=w)
             assert "not a pipe" not in caplog.text
         finally:
             os.close(r)
@@ -1852,14 +1852,14 @@ class TestStdioPipeAssertion:
     def test_regular_file_stdout_warns(self, tmp_path, caplog):
         """Reproducer for runtime#61: stdout redirected to a regular file.
         Now emits a warning instead of exiting."""
-        from a2a_mcp_server import _warn_if_stdio_not_pipe
+        from a2a_mcp_server import _assert_stdio_is_pipe_compatible
 
         r, _w = os.pipe()
         regular = tmp_path / "captured.log"
         f = open(regular, "wb")
         try:
             with caplog.at_level("WARNING"):
-                _warn_if_stdio_not_pipe(stdin_fd=r, stdout_fd=f.fileno())
+                _assert_stdio_is_pipe_compatible(stdin_fd=r, stdout_fd=f.fileno())
             assert "stdout" in caplog.text
             assert "not a pipe" in caplog.text
         finally:
@@ -1868,7 +1868,7 @@ class TestStdioPipeAssertion:
 
     def test_regular_file_stdin_warns(self, tmp_path, caplog):
         """Symmetric case — stdin redirected from a regular file."""
-        from a2a_mcp_server import _warn_if_stdio_not_pipe
+        from a2a_mcp_server import _assert_stdio_is_pipe_compatible
 
         regular = tmp_path / "input.json"
         regular.write_bytes(b'{"jsonrpc":"2.0","id":1,"method":"initialize"}\n')
@@ -1876,7 +1876,7 @@ class TestStdioPipeAssertion:
         _r, w = os.pipe()
         try:
             with caplog.at_level("WARNING"):
-                _warn_if_stdio_not_pipe(stdin_fd=f.fileno(), stdout_fd=w)
+                _assert_stdio_is_pipe_compatible(stdin_fd=f.fileno(), stdout_fd=w)
             assert "stdin" in caplog.text
             assert "not a pipe" in caplog.text
         finally:
@@ -1886,13 +1886,13 @@ class TestStdioPipeAssertion:
     def test_closed_fd_warns_about_stat_error(self, caplog):
         """If stdio is closed, os.fstat raises OSError. Warning is
         skipped silently (can't stat the fd)."""
-        from a2a_mcp_server import _warn_if_stdio_not_pipe
+        from a2a_mcp_server import _assert_stdio_is_pipe_compatible
 
         r, w = os.pipe()
         os.close(w)  # Now `w` is a stale fd — fstat will fail.
         try:
             with caplog.at_level("WARNING"):
-                _warn_if_stdio_not_pipe(stdin_fd=r, stdout_fd=w)
+                _assert_stdio_is_pipe_compatible(stdin_fd=r, stdout_fd=w)
             # No warning emitted because fstat failed before the check
             assert "not a pipe" not in caplog.text
         finally:

workspace/tests/test_a2a_tools_identity.py

@@ -0,0 +1,390 @@
+"""Tests for ``tool_get_runtime_identity`` and ``tool_update_agent_card``.
+
+These two MCP tools close the T4-tier workspace owner-permission gaps
+reported via the canvas:
+
+  - the agent could not update its own ``agent_card`` (no MCP tool
+    wrapped the existing ``POST /registry/update-card`` endpoint);
+  - the agent could not identify which model it was running (the
+    ``MODEL`` env var is injected by ``provisioner.workspace_provision``
+    but nothing surfaced it back to the agent).
+
+Ported from molecule-ai-workspace-runtime PR#17 (mirror-only repo;
+canonical edit point per ``reference_runtime_repo_is_mirror_only``).
+Adapted to core's conventions:
+
+  * tool functions return ``str`` (JSON-encoded), matching every other
+    tool in ``a2a_tools_*`` modules. Tests ``json.loads`` to inspect.
+  * permission check ``memory.write`` runs inline in
+    ``tool_update_agent_card`` (same pattern as
+    ``a2a_tools_memory.tool_commit_memory``).
+  * ``WORKSPACE_ID`` is read directly from ``os.environ`` — core does
+    not have the runtime's validated-cache layer (``molecule_runtime.
+    builtin_tools.validation``).
+"""
+from __future__ import annotations
+
+import json
+
+import pytest
+
+
+# --- Drift gate: re-export aliases on a2a_tools ------------------------------
+
+class TestBackCompatAliases:
+    """Pin that ``a2a_tools.tool_*`` resolves to the same callable as
+    ``a2a_tools_identity.tool_*``. Refactor wrapping (e.g. a doc-string
+    wrapper that loses the function identity) silently breaks call
+    sites that ``patch("a2a_tools.tool_update_agent_card", ...)`` —
+    this gate makes that drift fail fast."""
+
+    def test_tool_get_runtime_identity_alias(self):
+        import a2a_tools
+        import a2a_tools_identity
+        assert a2a_tools.tool_get_runtime_identity is a2a_tools_identity.tool_get_runtime_identity
+
+    def test_tool_update_agent_card_alias(self):
+        import a2a_tools
+        import a2a_tools_identity
+        assert a2a_tools.tool_update_agent_card is a2a_tools_identity.tool_update_agent_card
+
+
+# --- tool_get_runtime_identity ----------------------------------------------
+
+class TestGetRuntimeIdentity:
+    """The tool returns env-derived runtime identity. No HTTP call."""
+
+    @pytest.mark.asyncio
+    async def test_returns_all_known_env_fields(self, monkeypatch):
+        from a2a_tools_identity import tool_get_runtime_identity
+
+        monkeypatch.setenv("MODEL", "claude-opus-4-7")
+        monkeypatch.setenv("MODEL_PROVIDER", "anthropic")
+        monkeypatch.setenv("TIER", "T4")
+        monkeypatch.setenv("WORKSPACE_ID", "ws-abc")
+        monkeypatch.setenv("ADAPTER_MODULE", "adapter")
+        monkeypatch.setenv("MOLECULE_MODEL", "claude-opus-4-7")
+        monkeypatch.setenv("ANTHROPIC_BASE_URL", "https://api.anthropic.com")
+
+        out = await tool_get_runtime_identity()
+        # MCP tools return JSON-encoded strings (matches the contract
+        # every other tool_* in a2a_tools_* uses).
+        assert isinstance(out, str)
+        parsed = json.loads(out)
+
+        assert parsed["model"] == "claude-opus-4-7"
+        assert parsed["model_provider"] == "anthropic"
+        assert parsed["tier"] == "T4"
+        assert parsed["workspace_id"] == "ws-abc"
+        assert parsed["runtime"] == "adapter"
+        assert parsed["molecule_model"] == "claude-opus-4-7"
+        assert parsed["anthropic_base_url"] == "https://api.anthropic.com"
+
+    @pytest.mark.asyncio
+    async def test_missing_env_returns_empty_strings(self, monkeypatch):
+        """Tool MUST NOT raise when env vars are absent — every key is
+        present but the value is the empty string. The agent then knows
+        the slot exists but is unset."""
+        from a2a_tools_identity import tool_get_runtime_identity
+
+        for var in (
+            "MODEL", "MODEL_PROVIDER", "TIER", "WORKSPACE_ID",
+            "ADAPTER_MODULE", "MOLECULE_MODEL", "ANTHROPIC_BASE_URL",
+        ):
+            monkeypatch.delenv(var, raising=False)
+
+        parsed = json.loads(await tool_get_runtime_identity())
+        assert parsed["model"] == ""
+        assert parsed["model_provider"] == ""
+        assert parsed["tier"] == ""
+        assert parsed["workspace_id"] == ""
+        assert parsed["runtime"] == ""
+        assert parsed["molecule_model"] == ""
+        assert parsed["anthropic_base_url"] == ""
+
+    @pytest.mark.asyncio
+    async def test_no_http_call_made(self, monkeypatch):
+        """``get_runtime_identity`` is env-only — must not open
+        httpx.AsyncClient even if the call would otherwise succeed.
+        Tripwire any client construction."""
+        import httpx
+
+        from a2a_tools_identity import tool_get_runtime_identity
+
+        class _Tripwire:
+            def __init__(self, *_a, **_kw):
+                raise AssertionError(
+                    "tool_get_runtime_identity must not open httpx.AsyncClient"
+                )
+
+        monkeypatch.setattr(httpx, "AsyncClient", _Tripwire)
+        # Must not raise.
+        await tool_get_runtime_identity()
+
+    @pytest.mark.asyncio
+    async def test_helper_dict_matches_string_payload(self, monkeypatch):
+        """``_runtime_identity_payload`` is the dict-returning helper
+        used by both the public tool and tests. Verify the public tool
+        json.dumps the same dict — no field is dropped or renamed by
+        the encoding step."""
+        from a2a_tools_identity import (
+            _runtime_identity_payload,
+            tool_get_runtime_identity,
+        )
+
+        monkeypatch.setenv("MODEL", "claude-opus-4-7")
+        monkeypatch.setenv("TIER", "T4")
+        monkeypatch.setenv("WORKSPACE_ID", "ws-helper-check")
+
+        helper = _runtime_identity_payload()
+        tool_str = await tool_get_runtime_identity()
+        assert json.loads(tool_str) == helper
+
+
+# --- tool_update_agent_card -------------------------------------------------
+
+
+class _MockResponse:
+    def __init__(self, status_code: int, payload: dict):
+        self.status_code = status_code
+        self._payload = payload
+        self.text = json.dumps(payload)
+
+    def json(self):
+        return self._payload
+
+
+class _MockClient:
+    """Drop-in for httpx.AsyncClient context manager.
+
+    Records the URL + json body + headers the tool POSTed so the test
+    can assert against them. Returns the canned _MockResponse passed
+    in at construction time.
+    """
+
+    def __init__(self, *, response: _MockResponse, captured: dict):
+        self._response = response
+        self._captured = captured
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *_args):
+        return False
+
+    async def post(self, url, *, json=None, headers=None, **_kw):  # noqa: A002
+        self._captured["url"] = url
+        self._captured["json"] = json
+        self._captured["headers"] = headers
+        return self._response
+
+
+@pytest.fixture
+def _grant_memory_write(monkeypatch):
+    """Force the inline RBAC gate inside ``tool_update_agent_card`` to
+    succeed. The gate calls
+    ``a2a_tools_rbac.check_memory_write_permission`` which inspects
+    ``$MOLECULE_ROLES`` / the role table; the patch sidesteps that
+    machinery so tests can focus on the platform-call shape.
+    """
+    import a2a_tools_identity
+    monkeypatch.setattr(
+        a2a_tools_identity, "_check_memory_write_permission", lambda: True
+    )
+
+
+class TestUpdateAgentCard:
+    @pytest.mark.asyncio
+    async def test_posts_to_registry_update_card(
+        self, monkeypatch, _grant_memory_write,
+    ):
+        """Hits POST {PLATFORM_URL}/registry/update-card with the
+        workspace bearer and the {workspace_id, agent_card} body shape
+        the platform handler expects (workspace-server
+        ``internal/handlers/registry.go``)."""
+        import a2a_tools_identity
+
+        monkeypatch.setenv("WORKSPACE_ID", "ws-42")
+        # Ensure PLATFORM_URL re-import sees a deterministic value —
+        # a2a_client imports it at module load so we patch the symbol
+        # on a2a_tools_identity directly (the module's own reference).
+        monkeypatch.setattr(a2a_tools_identity, "PLATFORM_URL", "http://test.invalid")
+
+        captured: dict = {}
+        response = _MockResponse(200, {"status": "updated"})
+
+        def _client_factory(*_a, **_kw):
+            return _MockClient(response=response, captured=captured)
+
+        monkeypatch.setattr(a2a_tools_identity.httpx, "AsyncClient", _client_factory)
+        monkeypatch.setattr(
+            a2a_tools_identity, "_auth_headers_for_heartbeat",
+            lambda: {"Authorization": "Bearer ws-token-xyz"},
+        )
+
+        card = {"name": "agent-foo", "version": "0.1.0", "description": "demo"}
+        result_str = await a2a_tools_identity.tool_update_agent_card(card)
+        result = json.loads(result_str)
+
+        # URL: PLATFORM_URL + /registry/update-card
+        assert captured["url"] == "http://test.invalid/registry/update-card"
+
+        # The platform handler expects {workspace_id, agent_card}; the
+        # agent_card is the raw object the agent submitted.
+        body = captured["json"]
+        assert body["workspace_id"] == "ws-42"
+        assert body["agent_card"] == card
+
+        # Auth header from auth_headers_for_heartbeat is forwarded
+        # verbatim — same path commit_memory uses.
+        assert captured["headers"]["Authorization"] == "Bearer ws-token-xyz"
+
+        assert result["success"] is True
+        assert result["status"] == "updated"
+
+    @pytest.mark.asyncio
+    async def test_propagates_server_error(
+        self, monkeypatch, _grant_memory_write,
+    ):
+        """Non-200 from platform surfaces as a structured error to the
+        agent. The agent sees {success:false, status_code, error} and
+        can decide whether to retry, fall back, or escalate."""
+        import a2a_tools_identity
+
+        monkeypatch.setenv("WORKSPACE_ID", "ws-42")
+        monkeypatch.setattr(a2a_tools_identity, "PLATFORM_URL", "http://test.invalid")
+
+        captured: dict = {}
+        response = _MockResponse(400, {"error": "invalid card"})
+
+        monkeypatch.setattr(
+            a2a_tools_identity.httpx, "AsyncClient",
+            lambda *a, **kw: _MockClient(response=response, captured=captured),
+        )
+        monkeypatch.setattr(
+            a2a_tools_identity, "_auth_headers_for_heartbeat", lambda: {},
+        )
+
+        result = json.loads(
+            await a2a_tools_identity.tool_update_agent_card({"name": "x"})
+        )
+        assert result["success"] is False
+        assert result["status_code"] == 400
+        assert "invalid card" in str(result["error"]).lower()
+
+    @pytest.mark.asyncio
+    async def test_rejects_non_dict_card(self, _grant_memory_write):
+        """The MCP schema constrains transport callers to pass a dict;
+        in-process callers (tests, sibling modules) can still pass any
+        type. Reject non-dict defensively so the platform isn't asked
+        to validate JSON-encoded strings or lists."""
+        from a2a_tools_identity import tool_update_agent_card
+
+        result = json.loads(await tool_update_agent_card("not-a-dict"))
+        assert result["success"] is False
+        assert "dict" in str(result["error"]).lower()
+
+    @pytest.mark.asyncio
+    async def test_workspace_id_missing_returns_error(
+        self, monkeypatch, _grant_memory_write,
+    ):
+        """If WORKSPACE_ID is not set the tool refuses to issue the
+        request — it would otherwise POST with an empty workspace_id
+        and let the platform return a confusing 400."""
+        from a2a_tools_identity import tool_update_agent_card
+
+        monkeypatch.delenv("WORKSPACE_ID", raising=False)
+
+        result = json.loads(await tool_update_agent_card({"name": "x"}))
+        assert result["success"] is False
+        assert "workspace_id" in str(result["error"]).lower()
+
+    @pytest.mark.asyncio
+    async def test_denies_when_memory_write_permission_missing(self, monkeypatch):
+        """The agent's RBAC role must grant ``memory.write`` to update
+        the card. Read-only roles get an RBAC error string back
+        immediately, never touching the platform."""
+        import a2a_tools_identity
+
+        monkeypatch.setenv("WORKSPACE_ID", "ws-42")
+        monkeypatch.setattr(
+            a2a_tools_identity, "_check_memory_write_permission", lambda: False,
+        )
+
+        # Tripwire httpx — must not be called when RBAC denies.
+        import httpx
+
+        class _Tripwire:
+            def __init__(self, *_a, **_kw):
+                raise AssertionError("RBAC denial must short-circuit before httpx call")
+
+        monkeypatch.setattr(httpx, "AsyncClient", _Tripwire)
+
+        result = json.loads(
+            await a2a_tools_identity.tool_update_agent_card({"name": "x"}),
+        )
+        assert result["success"] is False
+        assert "memory.write" in str(result["error"]).lower()
+
+    @pytest.mark.asyncio
+    async def test_network_exception_returns_structured_error(
+        self, monkeypatch, _grant_memory_write,
+    ):
+        """A network exception (DNS failure, connect timeout, etc) is
+        wrapped into a structured error dict instead of bubbling up
+        to the MCP transport layer."""
+        import a2a_tools_identity
+
+        monkeypatch.setenv("WORKSPACE_ID", "ws-42")
+        monkeypatch.setattr(a2a_tools_identity, "PLATFORM_URL", "http://test.invalid")
+
+        class _ExplodingClient:
+            async def __aenter__(self):
+                return self
+
+            async def __aexit__(self, *_a):
+                return False
+
+            async def post(self, *_a, **_kw):
+                raise RuntimeError("simulated DNS failure")
+
+        monkeypatch.setattr(
+            a2a_tools_identity.httpx, "AsyncClient",
+            lambda *a, **kw: _ExplodingClient(),
+        )
+
+        result = json.loads(
+            await a2a_tools_identity.tool_update_agent_card({"name": "x"})
+        )
+        assert result["success"] is False
+        assert "network" in str(result["error"]).lower()
+
+
+# --- Registry contract ------------------------------------------------------
+
+
+class TestRegistryContract:
+    """Pin the new tools' registration in platform_tools.registry. The
+    structural tests in ``test_platform_tools.py`` already check
+    registry↔MCP alignment; these are tighter assertions specific to
+    the two new tools so a future contributor deleting one entry sees
+    a focused failure."""
+
+    def test_get_runtime_identity_in_registry(self):
+        from platform_tools.registry import by_name
+        spec = by_name("get_runtime_identity")
+        assert spec.section == "a2a"
+        # No input parameters — env-only call.
+        assert spec.input_schema == {"type": "object", "properties": {}}
+        # impl points at the actual tool function, not a shim.
+        from a2a_tools_identity import tool_get_runtime_identity
+        assert spec.impl is tool_get_runtime_identity
+
+    def test_update_agent_card_in_registry(self):
+        from platform_tools.registry import by_name
+        spec = by_name("update_agent_card")
+        assert spec.section == "a2a"
+        assert "card" in spec.input_schema["properties"]
+        assert spec.input_schema["required"] == ["card"]
+        from a2a_tools_identity import tool_update_agent_card
+        assert spec.impl is tool_update_agent_card