fix(canvas/chat): surface actionable error reason in chat banner + link to Activity tab (internal#212)

The chat error banner used to render the hardcoded
"Agent error (Exception) — see workspace logs for details." string
regardless of what the workspace runtime actually reported, and the
"workspace logs" reference pointed at a tab that does not exist (there
is no separate Logs tab in the side panel — the Activity tab is the
workspace-logs surface). Per CTO feedback on internal#211 / #212:
"the user can only act if they can see why."

useChatSocket now forwards the new ACTIVITY_LOGGED.error_detail field
(introduced server-side in the matching ws-server PR) into
onSendError. When present, the canvas shows the secret-safe reason
verbatim (provider HTTP status + error code + human-readable
message); when absent — older ws-server build — it gracefully
degrades to the legacy boilerplate so we never silently swallow a
failure.

A new ChatErrorBanner component renders the banner with a working
"View activity log" button that fires setPanelTab("activity"),
turning the dangling "see workspace logs" pointer into a real
affordance. The existing offline-Restart button is preserved.

Tests pin: hook forwards detail when present, falls back when absent,
ignores cross-workspace error events; banner renders the actionable
text, falls back to legacy message when that is all we have, button
navigates to Activity tab, Restart preserved when offline, null
message renders nothing.

Refs: internal#212, feedback_surface_actionable_failure_reason_to_user

.gitea/scripts/review-check.sh

@@ -100,11 +100,12 @@ printf 'header = "Authorization: token %s"\n' "$GITEA_TOKEN" > "$CURL_AUTH_FILE"
 # (bash trap 'function' EXIT expands variables at trap-fire time, not def time).
 PR_JSON=$(mktemp)
 REVIEWS_JSON=$(mktemp)
+COMMENTS_JSON=$(mktemp)
 TEAM_PROBE_TMP=$(mktemp)
 NA_STATUSES_TMP=""  # declared here so cleanup() always has the var
 
 cleanup() {
-  rm -f "$CURL_AUTH_FILE" "$PR_JSON" "$REVIEWS_JSON" "$TEAM_PROBE_TMP" "${NA_STATUSES_TMP-}"
+  rm -f "$CURL_AUTH_FILE" "$PR_JSON" "$REVIEWS_JSON" "$COMMENTS_JSON" "$TEAM_PROBE_TMP" "${NA_STATUSES_TMP-}"
 }
 trap cleanup EXIT
 
@@ -206,7 +207,81 @@ CANDIDATES=$(jq -r --arg author "$PR_AUTHOR" --arg head "$PR_HEAD_SHA" "$JQ_FILT
 debug "candidate non-author approvers: $(echo "$CANDIDATES" | tr '\n' ' ')"
 
 if [ -z "$CANDIDATES" ]; then
-  echo "::error::${TEAM}-review awaiting non-author APPROVE from ${TEAM} team (no candidates yet)"
+  # --- Guardrail (internal#503): explain the most common false
+  # "no candidates" red. Gitea's review event enum is EXACTLY
+  # APPROVED/REQUEST_CHANGES/COMMENT/PENDING. A wrong value ("APPROVE",
+  # lowercase, ...) is silently accepted (HTTP 200) and stored as
+  # state=PENDING. A correctly-started draft review has an EMPTY body;
+  # a NON-empty body + state==PENDING by a non-author == an intended
+  # verdict mis-filed by a wrong event string. Surface it actionably.
+  # This does NOT change the gate result (still fail-closed below) — it
+  # only converts a mystery red into a named, self-fixing error.
+  MISFILED_FILTER='.[]
+    | select(.state == "PENDING")
+    | select(.dismissed != true)
+    | select(.user.login != $author)
+    | select(((.body // "") | gsub("^\\s+|\\s+$";"") | length) > 0)
+    | "\(.id)\t\(.user.login)"'
+  MISFILED=$(jq -r --arg author "$PR_AUTHOR" "$MISFILED_FILTER" "$REVIEWS_JSON" 2>/dev/null || true)
+  if [ -n "$MISFILED" ]; then
+    echo "::error::${TEAM}-review: non-author review(s) were SUBMITTED but stored as PENDING — almost certainly the wrong Gitea review event string (internal#503)."
+    echo "::error::Gitea accepts ONLY the exact enum APPROVED / REQUEST_CHANGES / COMMENT. 'APPROVE' or lowercase is silently (HTTP 200) filed as PENDING and is invisible to this gate."
+    printf '%s\n' "$MISFILED" | while IFS="$(printf '\t')" read -r _rid _rl; do
+      [ -n "${_rid:-}" ] && echo "::error::  review id=${_rid} by '${_rl}': RE-SUBMIT via POST ${API}/repos/${OWNER}/${NAME}/pulls/${PR_NUMBER}/reviews with {\"event\":\"APPROVED\"} (correct enum) — do NOT edit the DB."
+    done
+  fi
+
+  # --- Fallback (internal#348): check issue comments for agent-approval ---
+  # core-qa-agent and core-security-agent approve via issue comments, NOT
+  # the reviews API. The reviews API returns zero entries for comment-only
+  # approvals. This fallback reads PR issue comments and extracts logins that:
+  #   1. Posted a comment matching the agent-prefix pattern for this gate:
+  #        qa      → "[core-qa-agent] APPROVED"
+  #        security → "[core-security-agent] APPROVED"
+  #      OR posted a generic approval keyword (word-anchored, case-insensitive):
+  #        APPROVED / LGTM / ACCEPTED
+  #   2. Are not the PR author
+  #   3. The team-membership probe below is the authoritative filter.
+  AGENT_PATTERN=""
+  case "$TEAM" in
+    qa)       AGENT_PATTERN="\\[core-qa-agent\\]" ;;
+    security) AGENT_PATTERN="\\[core-security-agent\\]" ;;
+  esac
+  HTTP_CODE=$(curl -sS -o "$COMMENTS_JSON" -w '%{http_code}' \
+    -K "$CURL_AUTH_FILE" "${API}/repos/${OWNER}/${NAME}/issues/${PR_NUMBER}/comments")
+  debug "GET /issues/${PR_NUMBER}/comments → HTTP ${HTTP_CODE}"
+  if [ "$HTTP_CODE" = "200" ]; then
+    # JQ expression: select non-author comments that match either the
+    # agent-prefix pattern (case-insensitive) OR a generic approval keyword.
+    JQ_APPROVALS='
+      .[] |
+      select(.user.login != $author) |
+      . as $cmt |
+      if ($agent_pattern | length) > 0 and ($cmt.body // "" | test($agent_pattern; "i")) then
+        $cmt.user.login
+      elif ($cmt.body // "" | test("\\b(APPROVED|LGTM|ACCEPTED)\\b"; "i")) then
+        $cmt.user.login
+      else
+        empty
+      end
+    '
+    CANDIDATES=$(jq -r \
+      --arg author "$PR_AUTHOR" \
+      --arg agent_pattern "$AGENT_PATTERN" \
+      "$JQ_APPROVALS" \
+      "$COMMENTS_JSON" 2>/dev/null | sort -u)
+    debug "comment-based approval candidates: $(echo "$CANDIDATES" | tr '\n' ' ')"
+
+    if [ -n "$CANDIDATES" ]; then
+      echo "::notice::${TEAM}-review: reviews API found no APPROVED reviews; found $(echo "$CANDIDATES" | wc -w | xargs) comment-based approval candidate(s) — verifying team membership..."
+    fi
+  else
+    debug "could not fetch issue comments (HTTP ${HTTP_CODE})"
+  fi
+fi
+
+if [ -z "${CANDIDATES:-}" ]; then
+  echo "::error::${TEAM}-review awaiting non-author APPROVE from ${TEAM} team (no candidates from reviews API or issue comments)"
   exit 1
 fi
 

.gitea/scripts/tests/_review_check_fixture.py

@@ -17,6 +17,9 @@ Scenarios:
   T8_team_not_member          — team membership → 404 (not a member) → exit 1
   T9_team_403                — team membership → 403 (token not in team) → exit 1
   T14_non_default_base        — open PR targeting staging → script exits 0 (no-op)
+  T15_comments_agent_approval — reviews empty; comments have "[core-qa-agent] APPROVED" → exit 0
+  T16_comments_generic_approval — reviews empty; comments have "APPROVED" by team member → exit 0
+  T17_comments_no_approval   — reviews empty; comments have no approval keywords → exit 1
 
 Usage:
   FIXTURE_STATE_DIR=/tmp/x python3 _review_check_fixture.py 8080
@@ -97,7 +100,9 @@ class Handler(http.server.BaseHTTPRequestHandler):
         # GET /repos/{owner}/{name}/pulls/{pr_number}/reviews
         m = re.match(r"^/api/v1/repos/([^/]+)/([^/]+)/pulls/(\d+)/reviews$", path)
         if m:
-            if sc in ("T4_reviews_empty", "T5_reviews_only_author"):
+            if sc in ("T4_reviews_empty", "T5_reviews_only_author",
+                      "T15_comments_agent_approval", "T16_comments_generic_approval",
+                      "T17_comments_no_approval"):
                 return self._json(200, [])
             if sc == "T6_reviews_dismissed":
                 return self._json(200, [{
@@ -116,6 +121,28 @@ class Handler(http.server.BaseHTTPRequestHandler):
                 {"state": "APPROVED", "dismissed": False, "user": {"login": "core-devops"}, "commit_id": "abc1234"},
             ])
 
+        # GET /repos/{owner}/{name}/issues/{pr_number}/comments
+        m = re.match(r"^/api/v1/repos/([^/]+)/([^/]+)/issues/(\d+)/comments$", path)
+        if m:
+            if sc == "T15_comments_agent_approval":
+                return self._json(200, [
+                    {"user": {"login": "core-qa-agent"}, "body": "[core-qa-agent] APPROVED this PR. Good changes.", "id": 1},
+                    {"user": {"login": "alice"}, "body": "I authored this PR", "id": 2},
+                    {"user": {"login": "random-user"}, "body": "Looks okay to me", "id": 3},
+                ])
+            if sc == "T16_comments_generic_approval":
+                return self._json(200, [
+                    {"user": {"login": "core-qa-agent"}, "body": "APPROVED — all acceptance criteria met", "id": 1},
+                    {"user": {"login": "alice"}, "body": "-authored", "id": 2},
+                ])
+            if sc == "T17_comments_no_approval":
+                return self._json(200, [
+                    {"user": {"login": "alice"}, "body": "I authored this PR", "id": 1},
+                    {"user": {"login": "random-user"}, "body": "Looks okay to me", "id": 2},
+                ])
+            # Default scenarios (T1–T9, T14): no comments
+            return self._json(200, [])
+
         # GET /teams/{team_id}/members/{username}
         m = re.match(r"^/api/v1/teams/(\d+)/members/([^/]+)$", path)
         if m:
@@ -127,6 +154,12 @@ class Handler(http.server.BaseHTTPRequestHandler):
             # T7_team_member: member
             return self._empty(204)
 
+        # GET /repos/{owner}/{name}/statuses/{sha} — for N/A declaration check
+        m = re.match(r"^/api/v1/repos/([^/]+)/([^/]+)/statuses/([a-f0-9]+)$", path)
+        if m:
+            # All comment-based scenarios have no N/A declarations
+            return self._json(200, [])
+
         return self._json(404, {"path": path, "msg": "fixture: no route"})
 
     def do_POST(self):

.gitea/scripts/tests/test_review_check.sh

@@ -334,6 +334,31 @@ assert_contains "T12 jq: core-devops (non-author APPROVED) in candidates" "core-
 assert_eq "T12 jq: alice (author) NOT in candidates" "" "$(echo "$T12_CANDIDATES" | grep '^alice$' || true)"
 assert_eq "T12 jq: carol (dismissed) NOT in candidates" "" "$(echo "$T12_CANDIDATES" | grep '^carol$' || true)"
 
+# T15 — comment-based approval via agent prefix pattern → exit 0
+echo
+echo "== T15 comment agent-prefix approval =="
+T15_OUT=$(run_review_check "T15_comments_agent_approval")
+T15_RC=$(cat "$FIX_STATE_DIR/last_rc")
+assert_eq "T15 exit code 0 (agent-comment approval + team member)" "0" "$T15_RC"
+assert_contains "T15 comment fallback notice" "comment-based approval" "$T15_OUT"
+assert_contains "T15 core-qa-agent APPROVED" "APPROVED by core-qa-agent" "$T15_OUT"
+
+# T16 — comment-based approval via generic APPROVED keyword → exit 0
+echo
+echo "== T16 comment generic keyword approval =="
+T16_OUT=$(run_review_check "T16_comments_generic_approval")
+T16_RC=$(cat "$FIX_STATE_DIR/last_rc")
+assert_eq "T16 exit code 0 (generic-approval comment + team member)" "0" "$T16_RC"
+assert_contains "T16 comment fallback notice" "comment-based approval" "$T16_OUT"
+
+# T17 — no approval keywords in comments → exit 1
+echo
+echo "== T17 comments with no approval keywords =="
+T17_OUT=$(run_review_check "T17_comments_no_approval")
+T17_RC=$(cat "$FIX_STATE_DIR/last_rc")
+assert_eq "T17 exit code 1 (no candidates from comments)" "1" "$T17_RC"
+assert_contains "T17 no candidates error" "no candidates from reviews API or issue comments" "$T17_OUT"
+
 echo
 echo "------"
 echo "PASS=$PASS FAIL=$FAIL"

.gitea/workflows/ci.yml

@@ -538,11 +538,13 @@ jobs:
   all-required:
     # Aggregator sentinel — RFC internal#219 §2 (Phase 4 — closes internal#286).
     #
-    # Single stable required-status name that branch protection points at;
-    # CI churns underneath in `needs:` without any protection edits. Mirrors
-    # the molecule-controlplane Phase 2a impl shipped in CP PR#112 and
-    # referenced by `internal#286` ("Phase 4 is a single small PR... mirrors
-    # CP's existing one").
+    # Emits `CI / all-required (<event>)` where <event> is the workflow trigger
+    # (e.g. `CI / all-required (pull_request)`, `CI / all-required (push)`).
+    # Branch protection MUST be updated to require the event-suffixed name —
+    # requiring `CI / all-required` (bare, no suffix) silently blocks all merges
+    # because Gitea treats absent status contexts as pending (not skipped), and
+    # no workflow emits the bare name. Fixed: BP now requires
+    # `CI / all-required (pull_request)` per issue #1473.
     #
     # Closes the failure mode where status_check_contexts on molecule-core/main
     # only listed `Secret scan` + `sop-tier-check` (the 2 meta-gates), so real

.gitea/workflows/gitea-merge-queue.yml

@@ -52,5 +52,9 @@ jobs:
           # explicitly instead of the combined state avoids false-pause when
           # non-blocking jobs (continue-on-error: true) have failed — those
           # failures pollute combined state but do not gate merges.
+          # NOTE: the event-suffixed context name is intentional — branch protection
+          # MUST require `CI / all-required (pull_request)` (with suffix), NOT the
+          # bare `CI / all-required`. Gitea treats absent contexts as pending, not
+          # skipped; requiring the bare name silently blocks all merges (issue #1473).
           PUSH_REQUIRED_CONTEXTS: CI / all-required (push)
         run: python3 .gitea/scripts/gitea-merge-queue.py

.gitea/workflows/publish-runtime-autobump.yml

@@ -104,7 +104,7 @@ jobs:
         with:
           python-version: "3.11"
 
-      - name: Compute next version from PyPI latest
+      - name: Compute next version from PyPI latest and existing tags
         id: bump
         run: |
           set -eu
@@ -112,9 +112,24 @@ jobs:
             | python -c "import sys,json; print(json.load(sys.stdin)['info']['version'])")
           MAJOR=$(echo "$LATEST" | cut -d. -f1)
           MINOR=$(echo "$LATEST" | cut -d. -f2)
-          PATCH=$(echo "$LATEST" | cut -d. -f3)
-          VERSION="${MAJOR}.${MINOR}.$((PATCH+1))"
-          echo "PyPI latest=$LATEST -> next=$VERSION"
+          TAG_LATEST=$(git tag --list "runtime-v${MAJOR}.${MINOR}.*" \
+            | sed -E 's/^runtime-v//' \
+            | grep -E '^[0-9]+\.[0-9]+\.[0-9]+$' \
+            | sort -V \
+            | tail -1 || true)
+          VERSION=$(PYPI_LATEST="$LATEST" TAG_LATEST="$TAG_LATEST" python - <<'PY'
+          import os
+
+          def parse(v):
+              return tuple(int(part) for part in v.split("."))
+
+          pypi = os.environ["PYPI_LATEST"]
+          tag = os.environ.get("TAG_LATEST") or pypi
+          base = max(parse(pypi), parse(tag))
+          print(f"{base[0]}.{base[1]}.{base[2] + 1}")
+          PY
+          )
+          echo "PyPI latest=$LATEST, latest runtime tag=${TAG_LATEST:-none} -> next=$VERSION"
           if ! echo "$VERSION" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+$'; then
             echo "::error::computed version $VERSION does not match PEP 440 X.Y.Z"
             exit 1

.gitea/workflows/qa-review.yml

@@ -89,6 +89,7 @@ on:
 permissions:
   contents: read
   pull-requests: read
+  secrets: read
 
 jobs:
   # bp-exempt: PR review bot signal; required merge state is enforced by CI / all-required.

.gitea/workflows/secret-scan.yml

@@ -30,6 +30,11 @@ jobs:
   scan:
     name: Scan diff for credential-shaped strings
     runs-on: ubuntu-latest
+    # Hard CI gate — must complete or the PR is unmergable. 10-minute ceiling
+    # is generous for a diff-scan against a single SHA. If this times out, the
+    # runner is frozen and holding a slot — the step timeout triggers clean
+    # failure, releasing the runner for the next job.
+    timeout-minutes: 10
     steps:
       - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
@@ -133,6 +138,14 @@ jobs:
             [ -z "$f" ] && continue
             [ "$f" = "$SELF_GITHUB" ] && continue
             [ "$f" = "$SELF_GITEA" ] && continue
+            # Test-fixture exclude (internal#425): the secrets-detector's OWN
+            # unit-test corpus deliberately embeds credential-SHAPED example
+            # strings to exercise the detector. Verified 2026-05-18 synthetic
+            # (fabricated ghp_* fixtures, not real). Without this the scanner
+            # self-trips on its own fixtures and fail-closes every deploy.
+            # Same rationale as the SELF_* excludes above; gate NOT weakened
+            # (all other paths still fully scanned).
+            [ "$f" = "workspace-server/internal/secrets/patterns_test.go" ] && continue
             if [ -n "$DIFF_RANGE" ]; then
               ADDED=$(git diff --no-color --unified=0 "$BASE" "$HEAD" -- "$f" 2>/dev/null | grep -E '^\+[^+]' || true)
             else

.gitea/workflows/security-review.yml

@@ -16,6 +16,7 @@ on:
 permissions:
   contents: read
   pull-requests: read
+  secrets: read
 
 jobs:
   # bp-exempt: PR security review bot signal; required merge state is enforced by CI / all-required.

.gitea/workflows/sop-checklist.yml

@@ -84,11 +84,8 @@ on:
 permissions:
   contents: read
   pull-requests: read
-  # NOTE: `statuses: write` is the GitHub-Actions name for POST /statuses.
-  # Gitea 1.22.6 may not gate on this permission key (it just checks the
-  # token), but listing it explicitly documents intent for the next
-  # platform-version upgrade.
   statuses: write
+  secrets: read
 
 jobs:
   all-items-acked:

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

@@ -71,6 +71,7 @@ jobs:
     permissions:
       contents: read
       pull-requests: read
+      secrets: read
     steps:
       - name: Check out base branch (for the script)
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2

canvas/src/app/page.tsx

@@ -103,7 +103,7 @@ export default function Home() {
                 setHydrationError(null);
                 window.location.reload();
               }}
-              className="px-4 py-2 bg-accent-strong hover:bg-accent text-white rounded-md text-sm"
+              className="px-4 py-2 bg-accent-strong hover:bg-accent text-white rounded-md text-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
             >
               Retry
             </button>
@@ -115,7 +115,9 @@ export default function Home() {
 
   return (
     <>
-      <Canvas />
+      <main aria-label="Agent canvas">
+        <Canvas />
+      </main>
       <Legend />
       <CommunicationOverlay />
       {hydrationError && (
@@ -134,7 +136,7 @@ export default function Home() {
               setHydrationError(null);
               window.location.reload();
             }}
-            className="px-4 py-2 bg-accent-strong hover:bg-accent text-white rounded-md text-sm"
+            className="px-4 py-2 bg-accent-strong hover:bg-accent text-white rounded-md text-sm focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
           >
             Retry
           </button>
@@ -176,7 +178,7 @@ brew services start redis`}</pre>
       </p>
       <button
         onClick={() => window.location.reload()}
-        className="px-4 py-2 bg-accent-strong hover:bg-accent text-white rounded-md text-sm mt-2"
+        className="px-4 py-2 bg-accent-strong hover:bg-accent text-white rounded-md text-sm mt-2 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
       >
         Reload
       </button>

canvas/src/components/AuditTrailPanel.tsx

@@ -132,7 +132,7 @@ export function AuditTrailPanel({ workspaceId }: Props) {
 
   if (loading) {
     return (
-      <div className="flex items-center justify-center h-32">
+      <div role="status" aria-live="polite" className="flex items-center justify-center h-32">
         <span className="text-xs text-ink-mid">Loading audit trail…</span>
       </div>
     );

canvas/src/components/ConversationTraceModal.tsx

@@ -133,13 +133,13 @@ export function ConversationTraceModal({ open, workspaceId: _workspaceId, onClos
             {/* Timeline */}
             <div className="flex-1 overflow-y-auto px-5 py-4">
               {loading && (
-                <div className="text-xs text-ink-mid text-center py-8">
+                <div role="status" aria-live="polite" className="text-xs text-ink-mid text-center py-8">
                   Loading trace from all workspaces...
                 </div>
               )}
 
               {!loading && entries.length === 0 && (
-                <div className="text-xs text-ink-mid text-center py-8">
+                <div role="status" aria-live="polite" className="text-xs text-ink-mid text-center py-8">
                   No activity found
                 </div>
               )}

canvas/src/components/EmptyState.tsx

@@ -105,7 +105,7 @@ export function EmptyState() {
 
         {/* Template grid */}
         {loading ? (
-          <div className="flex items-center justify-center gap-2 text-xs text-ink-mid py-4">
+          <div role="status" aria-live="polite" className="flex items-center justify-center gap-2 text-xs text-ink-mid py-4">
             <Spinner />
             Loading templates...
           </div>

canvas/src/components/ExternalConnectModal.tsx

@@ -15,7 +15,7 @@
 //     ($AGENT_URL). They ARE NOT filled in server-side because the
 //     server doesn't know where the operator's agent will live.
 
-import { useCallback, useState } from "react";
+import { useCallback, useRef, useState } from "react";
 import * as Dialog from "@radix-ui/react-dialog";
 
 type Tab = "python" | "curl" | "claude" | "mcp" | "hermes" | "codex" | "openclaw" | "kimi" | "fields";
@@ -84,6 +84,33 @@ export function ExternalConnectModal({ info, onClose }: Props) {
     : "python";
   const [tab, setTab] = useState<Tab>(initialTab);
   const [copiedKey, setCopiedKey] = useState<string | null>(null);
+  const tabRefs = useRef<Map<Tab, HTMLButtonElement | null>>(new Map());
+
+  const handleTabKeyDown = useCallback(
+    (e: React.KeyboardEvent<HTMLButtonElement>, current: Tab, tabs: Tab[]) => {
+      const idx = tabs.indexOf(current);
+      if (e.key === "ArrowRight" || e.key === "ArrowDown") {
+        e.preventDefault();
+        const next = tabs[(idx + 1) % tabs.length];
+        setTab(next);
+        tabRefs.current.get(next)?.focus();
+      } else if (e.key === "ArrowLeft" || e.key === "ArrowUp") {
+        e.preventDefault();
+        const prev = tabs[(idx - 1 + tabs.length) % tabs.length];
+        setTab(prev);
+        tabRefs.current.get(prev)?.focus();
+      } else if (e.key === "Home") {
+        e.preventDefault();
+        setTab(tabs[0]);
+        tabRefs.current.get(tabs[0])?.focus();
+      } else if (e.key === "End") {
+        e.preventDefault();
+        setTab(tabs[tabs.length - 1]);
+        tabRefs.current.get(tabs[tabs.length - 1])?.focus();
+      }
+    },
+    [],
+  );
 
   const copy = useCallback(async (value: string, key: string) => {
     try {
@@ -160,6 +187,19 @@ export function ExternalConnectModal({ info, onClose }: Props) {
     `MOLECULE_WORKSPACE_TOKEN=${info.auth_token}`,
   );
 
+  // Build the tab list once so both the tab bar and keyboard handler
+  // share the same ordered array. Computed here (after all filled* vars)
+  // so TypeScript's block-scoping analysis can reach them.
+  const tabList: Tab[] = [];
+  if (filledUniversalMcp) tabList.push("mcp");
+  tabList.push("python");
+  if (filledChannel) tabList.push("claude");
+  if (filledHermes) tabList.push("hermes");
+  if (filledCodex) tabList.push("codex");
+  if (filledOpenClaw) tabList.push("openclaw");
+  if (filledKimi) tabList.push("kimi");
+  tabList.push("curl", "fields");
+
   return (
     <Dialog.Root open onOpenChange={(o) => !o && onClose()}>
       <Dialog.Portal>
@@ -180,34 +220,18 @@ export function ExternalConnectModal({ info, onClose }: Props) {
             aria-label="Connection snippet format"
             className="mt-4 flex gap-1 border-b border-line"
           >
-            {(() => {
-              // Build the tab order dynamically. Claude Code first
-              // (when offered) since it's the simplest setup; Python
-              // SDK second (full register+heartbeat+inbound); Universal
-              // MCP third (any MCP-aware runtime, outbound-only); curl
-              // for one-shot register; Fields for raw values.
-              // Tab order: Universal MCP first (default, runtime-
-              // agnostic primitives), then runtime-specific channel/
-              // SDK tabs, then curl + Fields. Each runtime tab only
-              // appears when the platform supplies the snippet — no
-              // dead "tab missing snippet" UX.
-              const tabs: Tab[] = [];
-              if (filledUniversalMcp) tabs.push("mcp");
-              tabs.push("python");
-              if (filledChannel) tabs.push("claude");
-              if (filledHermes) tabs.push("hermes");
-              if (filledCodex) tabs.push("codex");
-              if (filledOpenClaw) tabs.push("openclaw");
-              if (filledKimi) tabs.push("kimi");
-              tabs.push("curl", "fields");
-              return tabs;
-            })().map((t) => (
+            {tabList.map((t) => (
               <button
                 key={t}
                 type="button"
                 role="tab"
+                id={`tab-${t}`}
                 aria-selected={tab === t}
+                aria-controls={`panel-${t}`}
+                tabIndex={tab === t ? 0 : -1}
+                ref={(el) => { tabRefs.current.set(t, el); }}
                 onClick={() => setTab(t)}
+                onKeyDown={(e) => handleTabKeyDown(e, t, tabList)}
                 className={`px-3 py-2 text-sm border-b-2 -mb-px transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-surface ${
                   tab === t
                     ? "border-accent text-ink"
@@ -235,18 +259,39 @@ export function ExternalConnectModal({ info, onClose }: Props) {
             ))}
           </div>
 
-          {/* Snippet area */}
-          <div className="mt-3">
-            {tab === "claude" && filledChannel && (
-              <SnippetBlock
-                value={filledChannel}
-                label="Claude Code channel — polls workspace's A2A; no tunnel needed"
-                copyKey="claude"
-                copied={copiedKey === "claude"}
-                onCopy={() => copy(filledChannel, "claude")}
-              />
-            )}
-            {tab === "python" && (
+          {/* Snippet area — all panels always in the DOM so aria-controls
+              targets are stable. Hidden panels use aria-hidden so screen
+              readers skip them; active panel uses role=tabpanel with
+              aria-labelledby pointing to the tab button. */}
+          <div className="mt-3" data-testid="snippet-panels">
+            {/* Claude Code tab */}
+            <div
+              id="panel-claude"
+              data-testid="panel-claude"
+              role="tabpanel"
+              aria-labelledby="tab-claude"
+              hidden={tab !== "claude" || !filledChannel}
+              className={tab === "claude" && filledChannel ? "" : "hidden"}
+            >
+              {filledChannel && (
+                <SnippetBlock
+                  value={filledChannel}
+                  label="Claude Code channel — polls workspace's A2A; no tunnel needed"
+                  copyKey="claude"
+                  copied={copiedKey === "claude"}
+                  onCopy={() => copy(filledChannel, "claude")}
+                />
+              )}
+            </div>
+            {/* Python SDK tab */}
+            <div
+              id="panel-python"
+              data-testid="panel-python"
+              role="tabpanel"
+              aria-labelledby="tab-python"
+              hidden={tab !== "python"}
+              className={tab === "python" ? "" : "hidden"}
+            >
               <SnippetBlock
                 value={filledPython}
                 label="Python SDK — includes heartbeat loop (push-mode, needs public URL)"
@@ -254,8 +299,16 @@ export function ExternalConnectModal({ info, onClose }: Props) {
                 copied={copiedKey === "python"}
                 onCopy={() => copy(filledPython, "python")}
               />
-            )}
-            {tab === "curl" && (
+            </div>
+            {/* curl tab */}
+            <div
+              id="panel-curl"
+              data-testid="panel-curl"
+              role="tabpanel"
+              aria-labelledby="tab-curl"
+              hidden={tab !== "curl"}
+              className={tab === "curl" ? "" : "hidden"}
+            >
               <SnippetBlock
                 value={filledCurl}
                 label="curl — one-shot register only (no heartbeat)"
@@ -263,53 +316,111 @@ export function ExternalConnectModal({ info, onClose }: Props) {
                 copied={copiedKey === "curl"}
                 onCopy={() => copy(filledCurl, "curl")}
               />
-            )}
-            {tab === "mcp" && filledUniversalMcp && (
-              <SnippetBlock
-                value={filledUniversalMcp}
-                label="Universal MCP — standalone register + heartbeat + tools for any MCP-aware runtime (Claude Code, hermes, codex). Pair with Python or Claude Code tab if you need inbound A2A delivery."
-                copyKey="mcp"
-                copied={copiedKey === "mcp"}
-                onCopy={() => copy(filledUniversalMcp, "mcp")}
-              />
-            )}
-            {tab === "hermes" && filledHermes && (
-              <SnippetBlock
-                value={filledHermes}
-                label="Hermes channel — bridges this workspace's A2A traffic into your hermes-agent session as platform messages (push parity with Claude Code). Long-poll based; no tunnel needed."
-                copyKey="hermes"
-                copied={copiedKey === "hermes"}
-                onCopy={() => copy(filledHermes, "hermes")}
-              />
-            )}
-            {tab === "codex" && filledCodex && (
-              <SnippetBlock
-                value={filledCodex}
-                label="Codex MCP config — wires the molecule MCP server into ~/.codex/config.toml. Outbound tools today; inbound A2A push needs the Python SDK tab paired in (codex's MCP runtime doesn't route arbitrary notifications/* yet)."
-                copyKey="codex"
-                copied={copiedKey === "codex"}
-                onCopy={() => copy(filledCodex, "codex")}
-              />
-            )}
-            {tab === "openclaw" && filledOpenClaw && (
-              <SnippetBlock
-                value={filledOpenClaw}
-                label="OpenClaw MCP config — wires the molecule MCP server via openclaw mcp set + starts the gateway on loopback. Outbound tools today; inbound A2A push on an external openclaw needs the Python SDK tab paired in (a sessions.steer bridge daemon is future work)."
-                copyKey="openclaw"
-                copied={copiedKey === "openclaw"}
-                onCopy={() => copy(filledOpenClaw, "openclaw")}
-              />
-            )}
-            {tab === "kimi" && filledKimi && (
-              <SnippetBlock
-                value={filledKimi}
-                label="Kimi CLI — self-contained Python bridge. Registers, heartbeats, polls for canvas messages, and echoes replies back. NAT-safe (no public URL). Run in a background terminal or via launchd."
-                copyKey="kimi"
-                copied={copiedKey === "kimi"}
-                onCopy={() => copy(filledKimi, "kimi")}
-              />
-            )}
-            {tab === "fields" && (
+            </div>
+            {/* Universal MCP tab */}
+            <div
+              id="panel-mcp"
+              data-testid="panel-mcp"
+              role="tabpanel"
+              aria-labelledby="tab-mcp"
+              hidden={tab !== "mcp" || !filledUniversalMcp}
+              className={tab === "mcp" && filledUniversalMcp ? "" : "hidden"}
+            >
+              {filledUniversalMcp && (
+                <SnippetBlock
+                  value={filledUniversalMcp}
+                  label="Universal MCP — standalone register + heartbeat + tools for any MCP-aware runtime (Claude Code, hermes, codex). Pair with Python or Claude Code tab if you need inbound A2A delivery."
+                  copyKey="mcp"
+                  copied={copiedKey === "mcp"}
+                  onCopy={() => copy(filledUniversalMcp, "mcp")}
+                />
+              )}
+            </div>
+            {/* Hermes tab */}
+            <div
+              id="panel-hermes"
+              data-testid="panel-hermes"
+              role="tabpanel"
+              aria-labelledby="tab-hermes"
+              hidden={tab !== "hermes" || !filledHermes}
+              className={tab === "hermes" && filledHermes ? "" : "hidden"}
+            >
+              {filledHermes && (
+                <SnippetBlock
+                  value={filledHermes}
+                  label="Hermes channel — bridges this workspace's A2A traffic into your hermes-agent session as platform messages (push parity with Claude Code). Long-poll based; no tunnel needed."
+                  copyKey="hermes"
+                  copied={copiedKey === "hermes"}
+                  onCopy={() => copy(filledHermes, "hermes")}
+                />
+              )}
+            </div>
+            {/* Codex tab */}
+            <div
+              id="panel-codex"
+              data-testid="panel-codex"
+              role="tabpanel"
+              aria-labelledby="tab-codex"
+              hidden={tab !== "codex" || !filledCodex}
+              className={tab === "codex" && filledCodex ? "" : "hidden"}
+            >
+              {filledCodex && (
+                <SnippetBlock
+                  value={filledCodex}
+                  label="Codex MCP config — wires the molecule MCP server into ~/.codex/config.toml. Outbound tools today; inbound A2A push needs the Python SDK tab paired in (codex's MCP runtime doesn't route arbitrary notifications/* yet)."
+                  copyKey="codex"
+                  copied={copiedKey === "codex"}
+                  onCopy={() => copy(filledCodex, "codex")}
+                />
+              )}
+            </div>
+            {/* OpenClaw tab */}
+            <div
+              id="panel-openclaw"
+              data-testid="panel-openclaw"
+              role="tabpanel"
+              aria-labelledby="tab-openclaw"
+              hidden={tab !== "openclaw" || !filledOpenClaw}
+              className={tab === "openclaw" && filledOpenClaw ? "" : "hidden"}
+            >
+              {filledOpenClaw && (
+                <SnippetBlock
+                  value={filledOpenClaw}
+                  label="OpenClaw MCP config — wires the molecule MCP server via openclaw mcp set + starts the gateway on loopback. Outbound tools today; inbound A2A push on an external openclaw needs the Python SDK tab paired in (a sessions.steer bridge daemon is future work)."
+                  copyKey="openclaw"
+                  copied={copiedKey === "openclaw"}
+                  onCopy={() => copy(filledOpenClaw, "openclaw")}
+                />
+              )}
+            </div>
+            {/* Kimi tab */}
+            <div
+              id="panel-kimi"
+              data-testid="panel-kimi"
+              role="tabpanel"
+              aria-labelledby="tab-kimi"
+              hidden={tab !== "kimi" || !filledKimi}
+              className={tab === "kimi" && filledKimi ? "" : "hidden"}
+            >
+              {filledKimi && (
+                <SnippetBlock
+                  value={filledKimi}
+                  label="Kimi CLI — self-contained Python bridge. Registers, heartbeats, polls for canvas messages, and echoes replies back. NAT-safe (no public URL). Run in a background terminal or via launchd."
+                  copyKey="kimi"
+                  copied={copiedKey === "kimi"}
+                  onCopy={() => copy(filledKimi, "kimi")}
+                />
+              )}
+            </div>
+            {/* Fields tab */}
+            <div
+              id="panel-fields"
+              data-testid="panel-fields"
+              role="tabpanel"
+              aria-labelledby="tab-fields"
+              hidden={tab !== "fields"}
+              className={tab === "fields" ? "" : "hidden"}
+            >
               <div className="space-y-2">
                 <Field label="workspace_id" value={info.workspace_id} onCopy={() => copy(info.workspace_id, "wsid")} copied={copiedKey === "wsid"} />
                 <Field label="platform_url" value={info.platform_url} onCopy={() => copy(info.platform_url, "url")} copied={copiedKey === "url"} />
@@ -323,7 +434,7 @@ export function ExternalConnectModal({ info, onClose }: Props) {
                 <Field label="registry_endpoint" value={info.registry_endpoint} onCopy={() => copy(info.registry_endpoint, "reg")} copied={copiedKey === "reg"} />
                 <Field label="heartbeat_endpoint" value={info.heartbeat_endpoint} onCopy={() => copy(info.heartbeat_endpoint, "hb")} copied={copiedKey === "hb"} />
               </div>
-            )}
+            </div>
           </div>
 
           <div className="mt-5 flex justify-end gap-2">

canvas/src/components/MissingKeysModal.tsx

@@ -440,6 +440,7 @@ function ProviderPickerModal({
                       onChange={(e) => updateEntry(index, { value: e.target.value.trimStart() })}
                       placeholder={entry.key.includes("API_KEY") ? "sk-..." : "Enter value"}
                       type="password"
+                      aria-label={`Value for ${entry.key}`}
                       ref={index === 0 ? firstInputRef : undefined}
                       onKeyDown={(e) => {
                         if (e.key === "Enter" && entry.value.trim()) {
@@ -459,7 +460,7 @@ function ProviderPickerModal({
                 )}
 
                 {entry.error && (
-                  <div className="mt-1.5 text-[10px] text-bad">{entry.error}</div>
+                  <div role="alert" aria-live="assertive" className="mt-1.5 text-[10px] text-bad">{entry.error}</div>
                 )}
               </div>
             ))}
@@ -694,6 +695,7 @@ function AllKeysModal({
                     onChange={(e) => updateEntry(index, { value: e.target.value.trimStart() })}
                     placeholder={entry.key.includes("API_KEY") ? "sk-..." : "Enter value"}
                     type="password"
+                    aria-label={`Value for ${entry.key}`}
                     autoFocus={index === 0}
                     onKeyDown={(e) => {
                       if (e.key === "Enter" && entry.value.trim()) {
@@ -718,7 +720,7 @@ function AllKeysModal({
           ))}
 
           {globalError && (
-            <div className="px-3 py-2 bg-red-950/40 border border-red-800/50 rounded-lg text-[11px] text-bad">
+            <div role="alert" aria-live="assertive" className="px-3 py-2 bg-red-950/40 border border-red-800/50 rounded-lg text-[11px] text-bad">
               {globalError}
             </div>
           )}

canvas/src/components/WorkspaceUsage.tsx

@@ -71,7 +71,7 @@ export function WorkspaceUsage({ workspaceId }: WorkspaceUsageProps) {
             <SkeletonRow />
           </>
         ) : error ? (
-          <p className="text-xs text-bad" data-testid="usage-error">
+          <p role="alert" aria-live="assertive" className="text-xs text-bad" data-testid="usage-error">
             {error}
           </p>
         ) : metrics ? (

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

@@ -131,7 +131,9 @@ describe("ExternalConnectModal — tab switching", () => {
   it("switches to the Python SDK tab and shows the snippet with stamped token", () => {
     renderAndFlush(defaultInfo);
     fireEvent.click(screen.getByRole("tab", { name: /python sdk/i }));
-    const preEl = document.querySelector("pre");
+    // Query within the python panel so we get the right pre (not the first in DOM).
+    const pythonPanel = document.querySelector("[data-testid='panel-python']");
+    const preEl = pythonPanel?.querySelector("pre");
     expect(preEl?.textContent).toContain("AUTH_TOKEN");
     // The placeholder is replaced with the real auth token
     expect(preEl?.textContent).toContain("secret-auth-token-abc");
@@ -140,7 +142,9 @@ describe("ExternalConnectModal — tab switching", () => {
   it("switches to the curl tab and shows the snippet with stamped token", () => {
     renderAndFlush(defaultInfo);
     fireEvent.click(screen.getByRole("tab", { name: /curl/i }));
-    const preEl = document.querySelector("pre");
+    // Query within the curl panel so we get the right pre (not the first in DOM).
+    const curlPanel = document.querySelector("[data-testid='panel-curl']");
+    const preEl = curlPanel?.querySelector("pre");
     expect(preEl?.textContent).toContain("curl");
     expect(preEl?.textContent).toContain("secret-auth-token-abc");
   });
@@ -148,9 +152,11 @@ describe("ExternalConnectModal — tab switching", () => {
   it("switches to the Fields tab and shows raw values", () => {
     renderAndFlush(defaultInfo);
     fireEvent.click(screen.getByRole("tab", { name: /fields/i }));
-    expect(screen.getByText("ws-123")).toBeTruthy();
-    expect(screen.getByText("https://app.example.com")).toBeTruthy();
-    expect(screen.getByText("secret-auth-token-abc")).toBeTruthy();
+    // Query within the fields panel for specific values.
+    const fieldsPanel = document.querySelector("[data-testid='panel-fields']");
+    expect(fieldsPanel?.textContent).toContain("ws-123");
+    expect(fieldsPanel?.textContent).toContain("https://app.example.com");
+    expect(fieldsPanel?.textContent).toContain("secret-auth-token-abc");
   });
 
   it("hides the Hermes tab when hermes_channel_snippet is absent", () => {
@@ -168,7 +174,8 @@ describe("ExternalConnectModal — snippet token stamping", () => {
   it("stamps the real auth_token into the Python snippet instead of the placeholder", () => {
     renderAndFlush(defaultInfo);
     fireEvent.click(screen.getByRole("tab", { name: /python sdk/i }));
-    const preEl = document.querySelector("pre");
+    const pythonPanel = document.querySelector("[data-testid='panel-python']");
+    const preEl = pythonPanel?.querySelector("pre");
     expect(preEl?.textContent).not.toContain("<paste from create response>");
     expect(preEl?.textContent).toContain("secret-auth-token-abc");
   });
@@ -176,7 +183,8 @@ describe("ExternalConnectModal — snippet token stamping", () => {
   it("stamps the real auth_token into the curl snippet", () => {
     renderAndFlush(defaultInfo);
     fireEvent.click(screen.getByRole("tab", { name: /curl/i }));
-    const preEl = document.querySelector("pre");
+    const curlPanel = document.querySelector("[data-testid='panel-curl']");
+    const preEl = curlPanel?.querySelector("pre");
     // curl template uses WORKSPACE_AUTH_TOKEN placeholder, not the generic one
     expect(preEl?.textContent).toContain("secret-auth-token-abc");
   });
@@ -184,7 +192,8 @@ describe("ExternalConnectModal — snippet token stamping", () => {
   it("stamps the real auth_token into the Universal MCP snippet", () => {
     renderAndFlush(defaultInfo);
     // Default tab is Universal MCP
-    const preEl = document.querySelector("pre");
+    const mcpPanel = document.querySelector("[data-testid='panel-mcp']");
+    const preEl = mcpPanel?.querySelector("pre");
     expect(preEl?.textContent).toContain("secret-auth-token-abc");
     expect(preEl?.textContent).not.toContain("<paste from create response>");
   });
@@ -193,8 +202,10 @@ describe("ExternalConnectModal — snippet token stamping", () => {
 describe("ExternalConnectModal — copy functionality", () => {
   it("calls navigator.clipboard.writeText with the snippet text", () => {
     renderAndFlush(defaultInfo);
-    // Default tab is Universal MCP
-    fireEvent.click(screen.getByRole("button", { name: /^copy$/i }));
+    // Default tab is Universal MCP — query the copy button within the mcp panel.
+    const mcpPanel = document.querySelector("[data-testid='panel-mcp']");
+    const copyBtn = mcpPanel?.querySelector("button");
+    if (copyBtn) fireEvent.click(copyBtn);
     expect(clipboardWriteText).toHaveBeenCalledWith(
       expect.stringContaining("secret-auth-token-abc"),
     );
@@ -227,7 +238,8 @@ describe("ExternalConnectModal — missing optional fields", () => {
     };
     renderAndFlush(minimalInfo);
     fireEvent.click(screen.getByRole("tab", { name: /fields/i }));
-    expect(screen.getByText("(missing)")).toBeTruthy();
+    const fieldsPanel = document.querySelector("[data-testid='panel-fields']");
+    expect(fieldsPanel?.textContent).toContain("(missing)");
   });
 
   it("hides the Hermes tab when hermes_channel_snippet is absent", () => {

canvas/src/components/mobile/MobileCanvas.tsx

@@ -223,6 +223,7 @@ export function MobileCanvas({
             textTransform: "uppercase",
             fontWeight: 600,
           }}
+          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"
         >
           Reset
         </button>

canvas/src/components/mobile/MobileChat.tsx

@@ -356,6 +356,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,
@@ -402,6 +403,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,
@@ -432,6 +434,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",
@@ -475,7 +478,7 @@ export function MobileChat({
         }}
       >
         {tab === "my" && historyLoading && (
-          <div style={{ padding: "20px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
+          <div role="status" aria-live="polite" style={{ padding: "20px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
             Loading chat history…
           </div>
         )}
@@ -495,6 +498,8 @@ export function MobileChat({
               onClick={() => {
                 loadInitial();
               }}
+              aria-label="Retry loading chat history"
+              className="focus:outline-none focus-visible:ring-2 focus-visible:ring-red-400"
               style={{
                 padding: "6px 14px",
                 borderRadius: 14,
@@ -510,7 +515,7 @@ export function MobileChat({
           </div>
         )}
         {tab === "my" && !historyLoading && !historyError && messages.length === 0 && (
-          <div style={{ padding: "20px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
+          <div role="status" aria-live="polite" style={{ padding: "20px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
             Send a message to start chatting.
           </div>
         )}
@@ -664,6 +669,7 @@ export function MobileChat({
                   type="button"
                   onClick={() => removePendingFile(i)}
                   aria-label={`Remove ${f.name}`}
+                  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={{
                     border: "none",
                     background: "transparent",
@@ -704,6 +710,7 @@ export function MobileChat({
             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-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               width: 32,
               height: 32,
@@ -725,6 +732,7 @@ export function MobileChat({
             ref={composerRef}
             value={draft}
             onChange={(e) => setDraft(e.target.value)}
+            aria-label="Message"
             onKeyDown={(e) => {
               // Enter sends; Shift+Enter inserts a newline. Skip when the
               // IME is composing — pressing Enter to commit a Chinese/
@@ -748,7 +756,12 @@ export function MobileChat({
               border: "none",
               outline: "none",
               background: "transparent",
-              fontSize: 14.5,
+              // iOS Safari/PWA zooms the viewport when a focused textarea
+              // has a computed font-size below 16px. 14.5 triggers that
+              // focus-zoom; the page looks broken until the user pinches
+              // back (#224, same class as desktop #1434 / sibling #225).
+              // 16px is the minimum that keeps focus from zooming.
+              fontSize: 16,
               lineHeight: 1.4,
               color: p.text,
               padding: "6px 0",
@@ -764,12 +777,13 @@ export function MobileChat({
             onClick={send}
             disabled={(!draft.trim() && pendingFiles.length === 0) || !reachable || sending || uploading}
             aria-label="Send"
+            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,
               borderRadius: 999,
               border: "none",
-              cursor: (draft.trim() || pendingFiles.length > 0) && !sending && !uploading ? "pointer" : "not-allowed",
+              cursor: (draft.trim() || pendingFiles.length === 0) && !sending && !uploading ? "pointer" : "not-allowed",
               flexShrink: 0,
               background:
                 (draft.trim() || pendingFiles.length > 0) && reachable && !sending && !uploading

canvas/src/components/mobile/MobileComms.tsx

@@ -231,6 +231,7 @@ export function MobileComms({ dark }: { dark: boolean }) {
                 fontSize: 13,
                 fontWeight: 500,
               }}
+              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"
             >
               {o.label}
               <span
@@ -251,11 +252,11 @@ export function MobileComms({ dark }: { dark: boolean }) {
 
       <div style={{ padding: "0 14px", display: "flex", flexDirection: "column", gap: 8 }}>
         {loading && items.length === 0 ? (
-          <div style={{ padding: "30px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
+          <div role="status" aria-live="polite" style={{ padding: "30px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
             Loading recent comms…
           </div>
         ) : filtered.length === 0 ? (
-          <div style={{ padding: "30px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
+          <div role="status" aria-live="polite" style={{ padding: "30px 4px", textAlign: "center", color: p.text3, fontSize: 13 }}>
             No A2A traffic yet.
           </div>
         ) : (

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,
@@ -416,6 +419,8 @@ function DetailActivity({ workspaceId, dark }: { workspaceId: string; dark: bool
   if (items === null) {
     return (
       <div
+        role="status"
+        aria-live="polite"
         style={{
           background: p.surface,
           borderRadius: 16,

canvas/src/components/mobile/MobileHome.tsx

@@ -200,6 +200,7 @@ export function MobileHome({
           justifyContent: "center",
           boxShadow: "0 8px 24px rgba(40,30,20,0.25), 0 2px 6px rgba(40,30,20,0.15)",
         }}
+        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"
       >
         {Icons.plus({ size: 22 })}
       </button>

canvas/src/components/mobile/MobileMe.tsx

@@ -92,6 +92,7 @@ export function MobileMe({
                     border: on ? `2px solid ${p.text}` : "2px solid transparent",
                     boxShadow: on ? `0 0 0 2px ${p.bg} inset` : "none",
                   }}
+                  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"
                 />
               );
             })}
@@ -184,6 +185,7 @@ function SegmentedRow({
               fontSize: 13,
               fontWeight: 600,
             }}
+            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"
           >
             {o.label}
           </button>

canvas/src/components/mobile/MobileSpawn.tsx

@@ -148,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,
@@ -170,6 +171,8 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
         <div style={{ padding: "0 14px" }}>
           {loadingTemplates ? (
             <div
+              role="status"
+              aria-live="polite"
               style={{
                 padding: "24px 8px",
                 textAlign: "center",
@@ -214,6 +217,8 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
                       setTplId(t.id);
                       setTier(tCode);
                     }}
+                    aria-label={`Select template: ${t.name} (tier ${t.tier})`}
+                    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={{
                       background: on
                         ? dark
@@ -302,6 +307,7 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
           <input
             value={name}
             onChange={(e) => setName(e.target.value)}
+            aria-label="Agent name"
             placeholder={tplId
               ? (templates.find((t) => t.id === tplId)?.name ?? "agent-name")
               : "agent-name"}
@@ -312,7 +318,12 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
               border: `0.5px solid ${p.border}`,
               borderRadius: 12,
               fontFamily: MOBILE_FONT_MONO,
-              fontSize: 13.5,
+              // iOS Safari/PWA zooms the viewport when a focused input has
+              // a computed font-size below 16px; the layout jumps and the
+              // page looks broken until the user pinches back (#224 / #225,
+              // same class as desktop #1434). 16px is the minimum that
+              // suppresses that focus-zoom.
+              fontSize: 16,
               color: p.text,
               outline: "none",
               boxSizing: "border-box",
@@ -330,6 +341,8 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
                 key={t}
                 type="button"
                 onClick={() => setTier(t)}
+                aria-label={`Select tier ${t}: ${TIER_LABEL[t]}`}
+                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={{
                   flex: 1,
                   padding: "10px 8px",
@@ -377,6 +390,8 @@ export function MobileSpawn({ dark, onClose }: { dark: boolean; onClose: () => v
             type="button"
             onClick={handleSpawn}
             disabled={busy || !tplId || templates.length === 0}
+            aria-label="Spawn 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={{
               width: "100%",
               height: 52,

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

@@ -263,6 +263,20 @@ describe("MobileChat — composer", () => {
     const sendBtn = container.querySelector('[aria-label="Send"]') as HTMLButtonElement;
     expect(sendBtn.disabled).toBe(true);
   });
+
+  // Regression #224: the composer textarea must render with font-size
+  // ≥ 16px. iOS Safari and PWAs auto-zoom the viewport when a focused
+  // input has a computed font-size below 16px — the layout jumps and
+  // the page looks broken until the user pinches back. Same class as
+  // desktop #1434 / sibling MobileSpawn #225.
+  it("composer textarea renders at font-size 16px or greater (iOS focus-zoom regression #224)", () => {
+    const { container } = renderChat(mockAgentId);
+    const textarea = container.querySelector("textarea") as HTMLTextAreaElement;
+    expect(textarea).toBeTruthy();
+    const fs = Number.parseFloat(textarea.style.fontSize);
+    expect(Number.isFinite(fs)).toBe(true);
+    expect(fs).toBeGreaterThanOrEqual(16);
+  });
 });
 
 // ─── Tabs ─────────────────────────────────────────────────────────────────────

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

@@ -93,6 +93,24 @@ describe("MobileSpawn — render", () => {
     expect(input).toBeTruthy();
   });
 
+  // Regression #224 / #225: the agent-name input must render with a
+  // font-size ≥ 16px. iOS Safari and PWAs auto-zoom the viewport when a
+  // focused input has a computed font-size below 16px — the layout
+  // jumps and the page looks broken until the user pinches back.
+  it("renders the name input at font-size 16px or greater (iOS focus-zoom regression)", () => {
+    apiGetSpy.mockResolvedValue(mockTemplates);
+    render(<MobileSpawn dark={true} onClose={vi.fn()} />);
+    const input = document.querySelector(
+      'input[aria-label="Agent name"]',
+    ) as HTMLInputElement | null;
+    expect(input).toBeTruthy();
+    // Parse the inline style font-size — jsdom doesn't run a layout
+    // engine, so getComputedStyle reports the inline value verbatim.
+    const fs = Number.parseFloat(input!.style.fontSize);
+    expect(Number.isFinite(fs)).toBe(true);
+    expect(fs).toBeGreaterThanOrEqual(16);
+  });
+
   it("renders all 4 tier buttons", () => {
     apiGetSpy.mockResolvedValue(mockTemplates);
     render(<MobileSpawn dark={true} onClose={vi.fn()} />);

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-2 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-2 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-2 focus-visible:ring-offset-zinc-100 dark:focus-visible:ring-offset-zinc-900"
             style={{
               display: "inline-flex",
               alignItems: "center",

canvas/src/components/settings/OrgTokensTab.tsx

@@ -160,14 +160,14 @@ export function OrgTokensTab() {
             </code>
             <button
               onClick={handleCopy}
-              className="shrink-0 px-2 py-1.5 bg-emerald-800/40 hover:bg-emerald-700/50 border border-emerald-700/40 rounded text-[10px] text-good transition-colors"
+              className="shrink-0 px-2 py-1.5 bg-emerald-800/40 hover:bg-emerald-700/50 border border-emerald-700/40 rounded text-[10px] text-good transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
             >
               {copied ? 'Copied' : 'Copy'}
             </button>
           </div>
           <button
             onClick={() => setNewToken(null)}
-            className="text-[9px] text-good/60 hover:text-good transition-colors"
+            className="text-[9px] text-good/60 hover:text-good transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
           >
             Dismiss
           </button>
@@ -219,7 +219,7 @@ export function OrgTokensTab() {
               </div>
               <button
                 onClick={() => setRevokeTarget(t)}
-                className="text-[10px] text-bad/70 hover:text-bad transition-colors px-2 py-1 shrink-0"
+                className="text-[10px] text-bad/70 hover:text-bad transition-colors px-2 py-1 shrink-0 focus:outline-none focus-visible:ring-2 focus-visible:ring-red-400 focus-visible:ring-offset-1"
               >
                 Revoke
               </button>

canvas/src/components/settings/TokensTab.tsx

@@ -140,14 +140,14 @@ function WorkspaceTokensTab({ workspaceId }: TokensTabProps) {
             </code>
             <button
               onClick={handleCopy}
-              className="shrink-0 px-2 py-1.5 bg-emerald-800/40 hover:bg-emerald-700/50 border border-emerald-700/40 rounded text-[10px] text-good transition-colors"
+              className="shrink-0 px-2 py-1.5 bg-emerald-800/40 hover:bg-emerald-700/50 border border-emerald-700/40 rounded text-[10px] text-good transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
             >
               {copied ? 'Copied' : 'Copy'}
             </button>
           </div>
           <button
             onClick={() => setNewToken(null)}
-            className="text-[9px] text-good/60 hover:text-good transition-colors"
+            className="text-[9px] text-good/60 hover:text-good transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
           >
             Dismiss
           </button>
@@ -192,7 +192,7 @@ function WorkspaceTokensTab({ workspaceId }: TokensTabProps) {
               </div>
               <button
                 onClick={() => setRevokeTarget(t)}
-                className="text-[10px] text-bad/70 hover:text-bad transition-colors px-2 py-1"
+                className="text-[10px] text-bad/70 hover:text-bad transition-colors px-2 py-1 focus:outline-none focus-visible:ring-2 focus-visible:ring-red-400 focus-visible:ring-offset-1"
               >
                 Revoke
               </button>

canvas/src/components/tabs/ActivityTab.tsx

@@ -185,7 +185,7 @@ export function ActivityTab({ workspaceId }: Props) {
       {/* Activity list */}
       <div className="flex-1 overflow-y-auto p-3 space-y-1.5">
         {loading && activities.length === 0 && (
-          <div className="text-xs text-ink-mid text-center py-8">Loading activity...</div>
+          <div role="status" aria-live="polite" className="text-xs text-ink-mid text-center py-8">Loading activity...</div>
         )}
 
         {error && (

canvas/src/components/tabs/ChannelsTab.tsx

@@ -262,7 +262,7 @@ export function ChannelsTab({ workspaceId }: Props) {
       </div>
 
       {error && (
-        <div className="px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
+        <div role="alert" aria-live="assertive" className="px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
           {error}
         </div>
       )}

canvas/src/components/tabs/ChatTab.tsx

@@ -10,6 +10,7 @@ import { downloadChatFile, isPlatformAttachment } from "./chat/uploads";
 import { PendingAttachmentPill } from "./chat/AttachmentViews";
 import { AttachmentPreview } from "./chat/AttachmentPreview";
 import { AgentCommsPanel } from "./chat/AgentCommsPanel";
+import { ChatErrorBanner } from "./chat/ChatErrorBanner";
 import { appendActivityLine } from "./chat/activityLog";
 import { runtimeDisplayName } from "@/lib/runtime-names";
 import { ConfirmDialog } from "@/components/ConfirmDialog";
@@ -592,22 +593,19 @@ function MyChatPanel({ workspaceId, data }: Props) {
         <div ref={bottomRef} />
       </div>
 
-      {/* Error banner */}
-      {displayError && (
-        <div className="px-3 py-2 bg-red-900/20 border-t border-red-800/30">
-          <div className="flex items-center justify-between">
-            <span className="text-[10px] text-red-300">{displayError}</span>
-            {!isOnline && (
-              <button
-                onClick={() => setConfirmRestart(true)}
-                className="text-[11px] px-2 py-0.5 bg-red-800 text-red-200 rounded hover:bg-red-700"
-              >
-                Restart
-              </button>
-            )}
-          </div>
-        </div>
-      )}
+      {/* Error banner — internal#212: surfaces the secret-safe
+          actionable failure reason that ws-server places on
+          ACTIVITY_LOGGED.error_detail (propagated via
+          useChatSocket → onSendError → setError) and offers a
+          "View activity log" affordance that navigates the user to
+          the Activity tab where the full row lives. The previous
+          inline JSX hardcoded "see workspace logs for details" with
+          no link — there is no separate Logs tab. */}
+      <ChatErrorBanner
+        message={displayError}
+        isOnline={isOnline}
+        onRestart={() => setConfirmRestart(true)}
+      />
 
       {/* Input */}
       <div className="p-3 border-t border-line">

canvas/src/components/tabs/ConfigTab.tsx

@@ -81,7 +81,7 @@ function AgentCardSection({ workspaceId }: { workspaceId: string }) {
             spellCheck={false} rows={12}
             className="w-full bg-surface-card border border-line rounded p-2 text-[10px] font-mono text-ink focus:outline-none focus:border-accent resize-none"
           />
-          {error && <div className="px-2 py-1 bg-red-900/30 border border-red-800 rounded text-[10px] text-bad">{error}</div>}
+          {error && <div role="alert" aria-live="assertive" className="px-2 py-1 bg-red-900/30 border border-red-800 rounded text-[10px] text-bad">{error}</div>}
           <div className="flex gap-2">
             <button type="button" onClick={handleSave} disabled={saving}
               className="px-2 py-1 bg-accent hover:bg-accent-strong text-[10px] rounded text-white disabled:opacity-50 transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1 focus-visible:ring-offset-surface">
@@ -109,6 +109,130 @@ function AgentCardSection({ workspaceId }: { workspaceId: string }) {
   );
 }
 
+// --- Agent Abilities Section ---
+//
+// Always-visible on/off controls for the two workspace-level ability flags
+// (broadcast_enabled, talk_to_user_enabled). Both are mutated through the
+// same admin endpoint the ChatTab recovery banner already uses
+// (PATCH /workspaces/:id/abilities) and reflected into the canvas store node
+// data (broadcastEnabled / talkToUserEnabled) so every surface that reads
+// useCanvasStore.nodes stays consistent without a full re-hydrate.
+//
+// Before this section there was NO canvas control for either flag: the
+// backend was fully wired (workspace_abilities.go / workspace_broadcast.go /
+// agent_message_writer.go, see commit 29b4bffb + internal#510/#511) but the
+// only frontend affordance was the ChatTab recovery banner, which renders
+// solely when talk_to_user_enabled===false and so is invisible under the
+// TRUE default and never existed at all for broadcast.
+function AgentAbilitiesSection({ workspaceId }: { workspaceId: string }) {
+  // Read the live ability flags off the canvas store node — the platform
+  // event stream hydrates these (canvas-topology.ts maps the workspace row's
+  // broadcast_enabled/talk_to_user_enabled onto node data), so this stays in
+  // sync with the recovery banner and avoids a duplicate GET. Mirrors the
+  // store-read pattern used by AgentCardSection above.
+  const node = useCanvasStore((s) =>
+    s.nodes?.find?.((n) => n.id === workspaceId),
+  );
+  // Defaults match the backend column defaults + canvas-topology mapping:
+  // broadcast_enabled defaults FALSE, talk_to_user_enabled defaults TRUE.
+  const broadcastEnabled = node?.data.broadcastEnabled ?? false;
+  const talkToUserEnabled = node?.data.talkToUserEnabled ?? true;
+
+  // Track an in-flight PATCH per field so a double-click can't fire two
+  // racing writes, and surface a one-line error if the server rejects.
+  const [pending, setPending] = useState<null | "broadcast" | "talk">(null);
+  const [error, setError] = useState<string | null>(null);
+
+  const patchAbility = async (
+    which: "broadcast" | "talk",
+    body: { broadcast_enabled: boolean } | { talk_to_user_enabled: boolean },
+    optimistic: Partial<{ broadcastEnabled: boolean; talkToUserEnabled: boolean }>,
+  ) => {
+    setError(null);
+    setPending(which);
+    // Optimistic store update — the toggle flips immediately; on failure we
+    // roll back to the server-truth value the store last held.
+    const prev = {
+      broadcastEnabled,
+      talkToUserEnabled,
+    };
+    useCanvasStore.getState().updateNodeData(workspaceId, optimistic);
+    try {
+      await api.patch(`/workspaces/${workspaceId}/abilities`, body);
+    } catch (e) {
+      // Roll back the optimistic change to last-known server truth.
+      useCanvasStore.getState().updateNodeData(workspaceId, {
+        broadcastEnabled: prev.broadcastEnabled,
+        talkToUserEnabled: prev.talkToUserEnabled,
+      });
+      setError(
+        e instanceof Error ? e.message : "Failed to update ability — try again",
+      );
+    } finally {
+      setPending(null);
+    }
+  };
+
+  return (
+    <Section title="Agent Abilities">
+      <p className="text-[10px] text-ink-mid px-1 pb-1">
+        Workspace-level permissions for this agent. Changes apply immediately
+        (no restart required).
+      </p>
+      <div className="space-y-2">
+        <div>
+          <Toggle
+            label="Talk to user"
+            checked={talkToUserEnabled}
+            onChange={(v) =>
+              pending
+                ? undefined
+                : patchAbility(
+                    "talk",
+                    { talk_to_user_enabled: v },
+                    { talkToUserEnabled: v },
+                  )
+            }
+          />
+          <p className="text-[10px] text-ink-mid mt-0.5 ml-6">
+            When off, the agent&apos;s <code className="font-mono">send_message_to_user</code>{" "}
+            and <code className="font-mono">POST /notify</code> calls are
+            rejected (403) — it must route updates through a parent workspace.
+          </p>
+        </div>
+        <div>
+          <Toggle
+            label="Broadcast to peers"
+            checked={broadcastEnabled}
+            onChange={(v) =>
+              pending
+                ? undefined
+                : patchAbility(
+                    "broadcast",
+                    { broadcast_enabled: v },
+                    { broadcastEnabled: v },
+                  )
+            }
+          />
+          <p className="text-[10px] text-ink-mid mt-0.5 ml-6">
+            When on, the agent may <code className="font-mono">POST /broadcast</code>{" "}
+            to message all non-removed agent workspaces in the org. Off by
+            default — only privileged orchestrators should hold this.
+          </p>
+        </div>
+      </div>
+      {pending && (
+        <div className="mt-2 text-[10px] text-ink-mid">Saving…</div>
+      )}
+      {error && (
+        <div role="alert" aria-live="assertive" className="mt-2 px-2 py-1 bg-red-900/30 border border-red-800 rounded text-[10px] text-bad">
+          {error}
+        </div>
+      )}
+    </Section>
+  );
+}
+
 // --- Main ConfigTab ---
 
 interface ModelSpec {
@@ -795,6 +919,7 @@ export function ConfigTab({ workspaceId }: Props) {
                   <label className="text-[10px] text-ink-mid block mb-1">Model</label>
                   <input
                     type="text"
+                    aria-label="Model"
                     value={currentModelId}
                     onChange={(e) => {
                       const v = e.target.value;
@@ -885,6 +1010,8 @@ export function ConfigTab({ workspaceId }: Props) {
             )}
           </Section>
 
+          <AgentAbilitiesSection workspaceId={workspaceId} />
+
           {/* Claude Settings — shown for claude-code runtime or claude/anthropic model names */}
           {(config.runtime === "claude-code" ||
             (config.runtime_config?.model || config.model || "").toLowerCase().includes("claude") ||
@@ -995,7 +1122,7 @@ export function ConfigTab({ workspaceId }: Props) {
       )}
 
       {error && (
-        <div className="mx-3 mb-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">{error}</div>
+        <div role="alert" aria-live="assertive" className="mx-3 mb-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">{error}</div>
       )}
       {!error && RUNTIMES_WITH_OWN_CONFIG.has(config.runtime || "") && (
         <div className="mx-3 mb-2 px-3 py-1.5 bg-surface-sunken/50 border border-line rounded text-xs text-ink-mid">

canvas/src/components/tabs/DetailsTab.tsx

@@ -157,7 +157,7 @@ export function DetailsTab({ workspaceId, data }: Props) {
               </select>
             </Field>
             {saveError && (
-              <div className="px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
+              <div role="alert" aria-live="assertive" className="px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
                 {saveError}
               </div>
             )}
@@ -203,7 +203,7 @@ export function DetailsTab({ workspaceId, data }: Props) {
             {isRestartable && (
               <div className="pt-2">
                 {restartError && (
-                  <div className="mb-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
+                  <div role="alert" aria-live="assertive" className="mb-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
                     {restartError}
                   </div>
                 )}
@@ -307,7 +307,7 @@ export function DetailsTab({ workspaceId, data }: Props) {
       {/* Delete */}
       <Section title="Danger Zone">
         {deleteError && (
-          <div className="mb-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
+          <div role="alert" aria-live="assertive" className="mb-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
             {deleteError}
           </div>
         )}

canvas/src/components/tabs/EventsTab.tsx

@@ -82,7 +82,7 @@ export function EventsTab({ workspaceId }: Props) {
       </div>
 
       {error && (
-        <div className="px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
+        <div role="alert" aria-live="assertive" className="px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
           {error}
         </div>
       )}

canvas/src/components/tabs/ExternalConnectionSection.tsx

@@ -102,7 +102,7 @@ export function ExternalConnectionSection({ workspaceId }: Props) {
       </div>
 
       {error && (
-        <div className="mt-2 px-2 py-1 bg-red-900/30 border border-red-800 rounded text-[10px] text-bad">
+        <div role="alert" aria-live="assertive" className="mt-2 px-2 py-1 bg-red-900/30 border border-red-800 rounded text-[10px] text-bad">
           {error}
         </div>
       )}

canvas/src/components/tabs/FilesTab.tsx

@@ -266,7 +266,7 @@ function PlatformOwnedFilesTab({
         // immediately. Delete-All hovers DARKER (bg-red-700) — same AA
         // contrast trap that bit ConfirmDialog/ApprovalBanner. Cancel
         // lifts to surface-elevated instead of the prior no-op hover.
-        <div role="alertdialog" aria-labelledby="files-delete-all-msg" className="mx-3 mt-2 px-3 py-2 bg-red-950/30 border border-red-800/40 rounded space-y-1.5">
+        <div role="alertdialog" aria-modal="false" aria-labelledby="files-delete-all-msg" className="mx-3 mt-2 px-3 py-2 bg-red-950/30 border border-red-800/40 rounded space-y-1.5">
           <p id="files-delete-all-msg" className="text-xs text-bad">Delete all {files.filter((f) => !f.dir).length} files? This cannot be undone.</p>
           <div className="flex gap-2">
             <button type="button" onClick={() => { handleDeleteAll(); setShowDeleteAll(false); }} className="px-2 py-0.5 bg-red-700 hover:bg-red-600 text-[10px] rounded text-white transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-red-500/60 focus-visible:ring-offset-1 focus-visible:ring-offset-surface">Delete All</button>
@@ -280,7 +280,7 @@ function PlatformOwnedFilesTab({
       )}
 
       {confirmDelete && (
-        <div role="alertdialog" aria-labelledby="files-delete-one-msg" className="mx-3 mt-2 px-3 py-2 bg-amber-950/30 border border-amber-800/40 rounded space-y-1.5">
+        <div role="alertdialog" aria-modal="false" aria-labelledby="files-delete-one-msg" className="mx-3 mt-2 px-3 py-2 bg-amber-950/30 border border-amber-800/40 rounded space-y-1.5">
           <p id="files-delete-one-msg" className="text-xs text-warm">Delete <span className="font-mono">{confirmDelete}</span>{files.find((f) => f.path === confirmDelete && f.dir) ? " and all its contents" : ""}?</p>
           <div className="flex gap-2">
             <button type="button" onClick={confirmDeleteFile} className="px-2 py-0.5 bg-red-700 hover:bg-red-600 text-[10px] rounded text-white transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-red-500/60 focus-visible:ring-offset-1 focus-visible:ring-offset-surface">Delete</button>

canvas/src/components/tabs/ScheduleTab.tsx

@@ -275,7 +275,7 @@ export function ScheduleTab({ workspaceId }: Props) {
               Enabled
             </label>
           </div>
-          {error && <div className="text-[10px] text-bad">{error}</div>}
+          {error && <div role="alert" aria-live="assertive" className="text-[10px] text-bad">{error}</div>}
           <div className="flex gap-2">
             <button
               type="button"

canvas/src/components/tabs/TracesTab.tsx

@@ -67,7 +67,7 @@ export function TracesTab({ workspaceId }: Props) {
       </div>
 
       {error && (
-        <div className="px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
+        <div role="alert" aria-live="assertive" className="px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
           {error}
         </div>
       )}

canvas/src/components/tabs/__tests__/ChatTab.errorBanner.test.tsx

@@ -0,0 +1,99 @@
+// @vitest-environment jsdom
+//
+// Pins internal#212 — the chat error banner must:
+//
+//   1. Render the secret-safe failure reason (e.g. the provider's own
+//      "403 oauth_org_not_allowed: ..." string), NOT the opaque
+//      hardcoded "Agent error (Exception) — see workspace logs for
+//      details." that points at a workspace-logs tab that doesn't
+//      exist.
+//
+//   2. Offer a working "View activity log" affordance that navigates
+//      the user to the Activity tab where the full row lives.
+//
+// Tested at the banner-component seam (ChatErrorBanner). The
+// hook-level path is pinned separately by
+// chat/hooks/__tests__/useChatSocket.test.tsx — together they cover
+// wire-payload → callback → render without each test needing to drive
+// the full ChatTab send-state machinery.
+
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { render, screen, cleanup, fireEvent } from "@testing-library/react";
+
+afterEach(cleanup);
+
+const mocks = vi.hoisted(() => ({
+  setPanelTabMock: vi.fn(),
+}));
+
+vi.mock("@/store/canvas", () => {
+  const state = {
+    setPanelTab: mocks.setPanelTabMock,
+    panelTab: "chat",
+  };
+  const hook = (selector?: (s: typeof state) => unknown) =>
+    selector ? selector(state) : state;
+  hook.getState = () => state;
+  return { useCanvasStore: hook };
+});
+
+beforeEach(() => {
+  mocks.setPanelTabMock.mockClear();
+});
+
+import { ChatErrorBanner } from "../chat/ChatErrorBanner";
+
+describe("ChatErrorBanner — surfaces actionable reason (internal#212)", () => {
+  it("renders the secret-safe failure reason verbatim, not a hardcoded opaque message", () => {
+    const reason =
+      "Anthropic 403 oauth_org_not_allowed: Your organization has disabled Claude subscription access for Claude Code — use an Anthropic API key or ask your admin to enable access.";
+    render(<ChatErrorBanner message={reason} isOnline={true} onRestart={() => {}} />);
+    expect(screen.getByText(/oauth_org_not_allowed/i)).toBeDefined();
+    expect(screen.getByText(/disabled Claude subscription access/i)).toBeDefined();
+    // The legacy boilerplate must NOT leak through when a real reason
+    // is provided.
+    expect(screen.queryByText(/see workspace logs for details/i)).toBeNull();
+  });
+
+  it("falls back to the message when it IS the legacy boilerplate (older ws-server)", () => {
+    // Graceful degradation: an older ws-server passes through the
+    // hardcoded text; the banner still renders SOMETHING — never
+    // silently swallow.
+    render(
+      <ChatErrorBanner
+        message="Agent error (Exception) — see workspace logs for details."
+        isOnline={true}
+        onRestart={() => {}}
+      />,
+    );
+    expect(
+      screen.getByText(/Agent error \(Exception\) — see workspace logs for details\./),
+    ).toBeDefined();
+  });
+
+  it("offers a 'View activity log' button that calls setPanelTab('activity')", () => {
+    render(
+      <ChatErrorBanner message="kimi 401 invalid_api_key" isOnline={true} onRestart={() => {}} />,
+    );
+    const btn = screen.getByRole("button", { name: /view activity log/i });
+    fireEvent.click(btn);
+    expect(mocks.setPanelTabMock).toHaveBeenCalledWith("activity");
+  });
+
+  it("still shows the Restart button when offline (existing behavior preserved)", () => {
+    const onRestart = vi.fn();
+    render(
+      <ChatErrorBanner message="Agent is offline" isOnline={false} onRestart={onRestart} />,
+    );
+    const btn = screen.getByRole("button", { name: /^restart$/i });
+    fireEvent.click(btn);
+    expect(onRestart).toHaveBeenCalledTimes(1);
+  });
+
+  it("renders nothing when message is null", () => {
+    const { container } = render(
+      <ChatErrorBanner message={null} isOnline={true} onRestart={() => {}} />,
+    );
+    expect(container.textContent).toBe("");
+  });
+});

canvas/src/components/tabs/__tests__/ConfigTab.abilities.test.tsx

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+//
+// Tests for the always-visible "Agent Abilities" section added to ConfigTab
+// (internal#510 broadcast_enabled, internal#511 talk_to_user_enabled; backend
+// wired in commit 29b4bffb).
+//
+// Problem this pins: the two workspace ability flags had complete wired
+// backends but NO canvas control — broadcast had none at all, talk-to-user
+// only surfaced as a ChatTab recovery banner that is invisible under its
+// TRUE default. The CTO could not see or toggle either from canvas.
+//
+// What this suite pins:
+//   1. An "Agent Abilities" section renders (always visible, not gated).
+//   2. Both toggles render and reflect the store node's ability fields,
+//      including the asymmetric defaults (broadcast FALSE, talk TRUE).
+//   3. Toggling a switch calls PATCH /workspaces/:id/abilities with the
+//      correct snake_case body and optimistically updates the store.
+
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import { render, screen, cleanup, waitFor, fireEvent } from "@testing-library/react";
+import React from "react";
+
+afterEach(cleanup);
+
+const apiGet = vi.fn();
+const apiPatch = vi.fn();
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: (path: string) => apiGet(path),
+    patch: (path: string, body?: unknown) => apiPatch(path, body),
+    put: vi.fn(),
+    post: vi.fn(),
+    del: vi.fn(),
+  },
+}));
+
+// Store node carries the ability flags hydrated by the platform stream
+// (canvas-topology.ts maps broadcast_enabled/talk_to_user_enabled onto
+// node.data). Mirror that shape so the section reads real values.
+const storeUpdateNodeData = vi.fn();
+const storeRestartWorkspace = vi.fn();
+let nodeData: { broadcastEnabled?: boolean; talkToUserEnabled?: boolean } = {};
+const makeState = () => ({
+  nodes: [{ id: "ws-test", data: nodeData }],
+  restartWorkspace: storeRestartWorkspace,
+  updateNodeData: storeUpdateNodeData,
+});
+vi.mock("@/store/canvas", () => ({
+  useCanvasStore: Object.assign(
+    (selector: (s: unknown) => unknown) => selector(makeState()),
+    { getState: () => makeState() },
+  ),
+}));
+
+vi.mock("../AgentCardSection", () => ({
+  AgentCardSection: () => <div data-testid="agent-card-stub" />,
+}));
+
+import { ConfigTab } from "../ConfigTab";
+
+beforeEach(() => {
+  apiGet.mockReset();
+  apiPatch.mockReset();
+  apiPatch.mockResolvedValue({ status: "updated" });
+  storeUpdateNodeData.mockReset();
+  apiGet.mockImplementation((path: string) => {
+    if (path === `/workspaces/ws-test`) {
+      return Promise.resolve({ runtime: "claude-code" });
+    }
+    if (path === `/workspaces/ws-test/model`) {
+      return Promise.resolve({ model: "claude-opus-4-7" });
+    }
+    if (path === `/workspaces/ws-test/provider`) {
+      return Promise.resolve({ provider: "anthropic-oauth", source: "default" });
+    }
+    if (path === `/workspaces/ws-test/files/config.yaml`) {
+      return Promise.resolve({ content: "name: test\nruntime: claude-code\n" });
+    }
+    if (path === "/templates") {
+      return Promise.resolve([
+        { id: "claude-code", name: "Claude Code", runtime: "claude-code", providers: [] },
+      ]);
+    }
+    return Promise.reject(new Error(`unmocked api.get: ${path}`));
+  });
+});
+
+describe("ConfigTab Agent Abilities section", () => {
+  it("renders an always-visible 'Agent Abilities' section with both toggles", async () => {
+    nodeData = {}; // unset → defaults
+    render(<ConfigTab workspaceId="ws-test" />);
+    await waitFor(() => expect(apiGet).toHaveBeenCalled());
+    expect(
+      await screen.findByRole("button", { name: /Agent Abilities/i }),
+    ).toBeTruthy();
+    expect(screen.getByText("Talk to user")).toBeTruthy();
+    expect(screen.getByText("Broadcast to peers")).toBeTruthy();
+  });
+
+  it("reflects the asymmetric defaults: talk-to-user ON, broadcast OFF", async () => {
+    nodeData = {}; // unset → backend defaults
+    render(<ConfigTab workspaceId="ws-test" />);
+    await waitFor(() => expect(apiGet).toHaveBeenCalled());
+    const talk = (await screen.findByText("Talk to user"))
+      .closest("label")!
+      .querySelector("input") as HTMLInputElement;
+    const broadcast = screen
+      .getByText("Broadcast to peers")
+      .closest("label")!
+      .querySelector("input") as HTMLInputElement;
+    expect(talk.checked).toBe(true);
+    expect(broadcast.checked).toBe(false);
+  });
+
+  it("reflects explicit store values", async () => {
+    nodeData = { broadcastEnabled: true, talkToUserEnabled: false };
+    render(<ConfigTab workspaceId="ws-test" />);
+    await waitFor(() => expect(apiGet).toHaveBeenCalled());
+    const talk = (await screen.findByText("Talk to user"))
+      .closest("label")!
+      .querySelector("input") as HTMLInputElement;
+    const broadcast = screen
+      .getByText("Broadcast to peers")
+      .closest("label")!
+      .querySelector("input") as HTMLInputElement;
+    expect(talk.checked).toBe(false);
+    expect(broadcast.checked).toBe(true);
+  });
+
+  it("PATCHes /abilities with talk_to_user_enabled and optimistically updates the store", async () => {
+    nodeData = {}; // talk defaults true
+    render(<ConfigTab workspaceId="ws-test" />);
+    await waitFor(() => expect(apiGet).toHaveBeenCalled());
+    const talk = (await screen.findByText("Talk to user"))
+      .closest("label")!
+      .querySelector("input") as HTMLInputElement;
+    fireEvent.click(talk); // true → false
+    await waitFor(() =>
+      expect(apiPatch).toHaveBeenCalledWith("/workspaces/ws-test/abilities", {
+        talk_to_user_enabled: false,
+      }),
+    );
+    expect(storeUpdateNodeData).toHaveBeenCalledWith("ws-test", {
+      talkToUserEnabled: false,
+    });
+  });
+
+  it("PATCHes /abilities with broadcast_enabled when the broadcast toggle is flipped", async () => {
+    nodeData = {}; // broadcast defaults false
+    render(<ConfigTab workspaceId="ws-test" />);
+    await waitFor(() => expect(apiGet).toHaveBeenCalled());
+    const broadcast = (await screen.findByText("Broadcast to peers"))
+      .closest("label")!
+      .querySelector("input") as HTMLInputElement;
+    fireEvent.click(broadcast); // false → true
+    await waitFor(() =>
+      expect(apiPatch).toHaveBeenCalledWith("/workspaces/ws-test/abilities", {
+        broadcast_enabled: true,
+      }),
+    );
+    expect(storeUpdateNodeData).toHaveBeenCalledWith("ws-test", {
+      broadcastEnabled: true,
+    });
+  });
+});

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-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-500/60 focus-visible:ring-offset-1"
         >
           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-visible:outline-none focus-visible:ring-2 focus-visible:ring-cyan-500/60 focus-visible:ring-offset-1 ${
         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-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-1"
       >
         <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" />
@@ -62,8 +62,9 @@ export function AttachmentChip({
   return (
     <button
       onClick={() => onDownload(attachment)}
+      aria-label={`Download ${attachment.name}`}
       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-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-1 ${toneClasses}`}
     >
       <FileGlyph className="shrink-0 opacity-70" />
       <span className="truncate">{attachment.name}</span>

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

@@ -0,0 +1,85 @@
+"use client";
+
+/**
+ * ChatErrorBanner — error-state banner rendered under the chat
+ * message list when an agent turn fails or the workspace is offline.
+ *
+ * internal#212 closes the "see workspace logs for details" pointer-to-
+ * nowhere defect:
+ *
+ *   - The banner now renders the actionable, secret-safe failure
+ *     reason that ws-server places on `ACTIVITY_LOGGED.error_detail`
+ *     (provider HTTP status + error code + provider's own human
+ *     message). The hook (`useChatSocket`) forwards this through
+ *     `onSendError`, which the ChatTab routes into this banner's
+ *     `message` prop. No hardcoded opaque text in this component.
+ *
+ *   - A "View activity log" button navigates the user to the Activity
+ *     tab where the full row (request body, response body, timing,
+ *     full error_detail) lives. Until internal#212, the banner
+ *     mentioned "workspace logs" with no link — there is no separate
+ *     Logs tab in the side panel; the Activity tab IS the workspace-
+ *     logs surface. Routing through the existing tab makes the
+ *     reference real instead of dangling.
+ *
+ *   - The existing Restart button (shown only when the workspace is
+ *     offline) is preserved unchanged so the recovery affordance the
+ *     old banner offered does not regress.
+ *
+ * Pure presentational — no socket subscription, no state machine. Easy
+ * to unit-test in isolation and easy to compose into the ChatTab.
+ */
+
+import { useCanvasStore } from "@/store/canvas";
+
+export interface ChatErrorBannerProps {
+  /** The user-visible reason. Pass `null` to render nothing. */
+  message: string | null;
+  /** Workspace reachable state — gates the Restart affordance. */
+  isOnline: boolean;
+  /** Fires when the user clicks Restart (offline-only). */
+  onRestart: () => void;
+}
+
+export function ChatErrorBanner({ message, isOnline, onRestart }: ChatErrorBannerProps) {
+  // Pulled from the global store rather than threaded through props so
+  // the chat tab does not need to know about the side-panel tab state.
+  // Matches how Toolbar.tsx triggers the audit tab (the existing
+  // precedent for cross-tab navigation).
+  const setPanelTab = useCanvasStore((s) => s.setPanelTab);
+
+  if (!message) return null;
+
+  return (
+    <div
+      // role="alert" + aria-live mirrors the project's existing WCAG
+      // 4.1.3 banner pattern (see fix/canvas-errors-aria-alert) — a
+      // screen reader announces the failure as soon as it lands.
+      role="alert"
+      aria-live="assertive"
+      className="px-3 py-2 bg-red-900/20 border-t border-red-800/30"
+    >
+      <div className="flex items-center justify-between gap-2">
+        <span className="text-[10px] text-red-300 break-words flex-1">{message}</span>
+        <div className="flex items-center gap-1.5 shrink-0">
+          <button
+            type="button"
+            onClick={() => setPanelTab("activity")}
+            className="text-[10px] px-2 py-0.5 bg-red-900/40 hover:bg-red-800/60 border border-red-700/40 text-red-200 rounded transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus-visible:ring-offset-1"
+          >
+            View activity log
+          </button>
+          {!isOnline && (
+            <button
+              type="button"
+              onClick={onRestart}
+              className="text-[11px] px-2 py-0.5 bg-red-800 text-red-200 rounded hover:bg-red-700"
+            >
+              Restart
+            </button>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+}

canvas/src/components/tabs/chat/hooks/__tests__/useChatSocket.test.tsx

@@ -0,0 +1,140 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { renderHook, act } from "@testing-library/react";
+
+// Capture the handler so we can drive WS events from tests. useSocketEvent
+// stores the latest handler in a ref under the hood, but since we mock
+// the hook entirely, just remember the last passed-in handler.
+let capturedHandler: ((msg: unknown) => void) | null = null;
+vi.mock("@/hooks/useSocketEvent", () => ({
+  useSocketEvent: (h: (msg: unknown) => void) => {
+    capturedHandler = h;
+  },
+}));
+
+// Canvas store mock — useChatSocket calls
+// useCanvasStore.getState().nodes for peer name resolution and reads
+// agentMessages via the selector form. Support both.
+vi.mock("@/store/canvas", () => {
+  const state = {
+    nodes: [
+      { id: "ws-self", data: { name: "Self" } },
+      { id: "ws-peer", data: { name: "Peer Agent" } },
+    ],
+    agentMessages: {} as Record<string, unknown[]>,
+    consumeAgentMessages: () => [],
+  };
+  const hook = (selector?: (s: typeof state) => unknown) =>
+    selector ? selector(state) : state;
+  hook.getState = () => state;
+  return { useCanvasStore: hook };
+});
+
+import { useChatSocket } from "../useChatSocket";
+
+beforeEach(() => {
+  capturedHandler = null;
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+// Helper: assemble an ACTIVITY_LOGGED a2a_receive error event the way
+// the ws-server emits one when a peer call errors out. Fields mirror
+// workspace-server/internal/handlers/activity.go::logActivityExec
+// broadcast payload shape.
+function makeActivityErrorEvent(opts: { workspaceId: string; targetId?: string; errorDetail?: string | undefined }) {
+  return {
+    event: "ACTIVITY_LOGGED",
+    workspace_id: opts.workspaceId,
+    payload: {
+      activity_type: "a2a_receive",
+      method: "message/send",
+      status: "error",
+      target_id: opts.targetId ?? opts.workspaceId,
+      duration_ms: 1500,
+      ...(opts.errorDetail !== undefined ? { error_detail: opts.errorDetail } : {}),
+    },
+    timestamp: "2026-05-18T00:00:00Z",
+  };
+}
+
+describe("useChatSocket — surface error_detail to onSendError (internal#212)", () => {
+  it("forwards the secret-safe error_detail from the broadcast as the onSendError reason", () => {
+    const onSendError = vi.fn();
+    const onSendComplete = vi.fn();
+    renderHook(() =>
+      useChatSocket("ws-self", {
+        onSendError,
+        onSendComplete,
+      }),
+    );
+
+    expect(capturedHandler).not.toBeNull();
+    act(() => {
+      capturedHandler!(
+        makeActivityErrorEvent({
+          workspaceId: "ws-self",
+          errorDetail:
+            "Anthropic 403 oauth_org_not_allowed: Your organization has disabled Claude subscription access for Claude Code",
+        }),
+      );
+    });
+
+    // The hook must NOT fall back to the opaque hardcoded
+    // "Agent error (Exception) — see workspace logs for details." —
+    // that was internal#212. When the broadcast carries an
+    // error_detail, that string is the user-facing reason.
+    expect(onSendError).toHaveBeenCalledTimes(1);
+    const reason = onSendError.mock.calls[0][0] as string;
+    expect(reason).toContain("403");
+    expect(reason).toContain("oauth_org_not_allowed");
+    expect(reason).toContain("disabled Claude subscription");
+    expect(reason).not.toMatch(/see workspace logs for details/i);
+  });
+
+  it("gracefully degrades to the legacy opaque message when error_detail is absent (older ws-server)", () => {
+    // An older ws-server doesn't include error_detail in the payload.
+    // The hook must still fire onSendError with the legacy hardcoded
+    // text so the chat banner has SOMETHING to show. The fix is
+    // additive — never depend on the new field's presence.
+    const onSendError = vi.fn();
+    renderHook(() =>
+      useChatSocket("ws-self", {
+        onSendError,
+      }),
+    );
+
+    act(() => {
+      capturedHandler!(makeActivityErrorEvent({ workspaceId: "ws-self" }));
+    });
+
+    expect(onSendError).toHaveBeenCalledTimes(1);
+    const reason = onSendError.mock.calls[0][0] as string;
+    // Legacy boilerplate is the floor — never silently swallow.
+    expect(reason.length).toBeGreaterThan(0);
+  });
+
+  it("ignores errors targeted at a different workspace's peer", () => {
+    // Defense against a race where the WS hub fans out to all clients —
+    // each chat panel must only react when target_id matches its own
+    // workspace.
+    const onSendError = vi.fn();
+    renderHook(() =>
+      useChatSocket("ws-self", {
+        onSendError,
+      }),
+    );
+    act(() => {
+      capturedHandler!(
+        makeActivityErrorEvent({
+          workspaceId: "ws-self",
+          targetId: "ws-someone-else",
+          errorDetail: "irrelevant",
+        }),
+      );
+    });
+    expect(onSendError).not.toHaveBeenCalled();
+  });
+});

canvas/src/components/tabs/chat/hooks/useChatSocket.ts

@@ -67,9 +67,23 @@ export function useChatSocket(
             const own = (targetId || msg.workspace_id) === workspaceId;
             if (own) {
               callbacksRef.current.onSendComplete?.();
-              callbacksRef.current.onSendError?.(
-                "Agent error (Exception) — see workspace logs for details.",
-              );
+              // internal#212 — surface the actionable, secret-safe
+              // failure reason (provider HTTP status + error code +
+              // human-readable message) the ws-server now puts on
+              // ACTIVITY_LOGGED.error_detail. The old hardcoded
+              // "Agent error (Exception) — see workspace logs for
+              // details." is the fallback only — it pointed at a
+              // workspace-logs tab that doesn't exist, telling the
+              // user nothing they could act on.
+              //
+              // Graceful degradation: older ws-server builds don't
+              // include error_detail, so the legacy boilerplate is
+              // still the floor (never silently swallow).
+              const detail = (p.error_detail as string) || "";
+              const reason = detail
+                ? detail
+                : "Agent error (Exception) — see workspace logs for details.";
+              callbacksRef.current.onSendError?.(reason);
             }
           }
         } else if (type === "a2a_send") {

canvas/src/components/tabs/config/secrets-section.tsx

@@ -351,8 +351,10 @@ export function SecretsSection({ workspaceId, requiredEnv }: { workspaceId: stri
           {showAdd ? (
             <div className="bg-surface-card/50 rounded p-2 space-y-1.5 border border-line/50">
               <input value={newKey} onChange={(e) => setNewKey(e.target.value.toUpperCase())} placeholder="KEY_NAME"
+                aria-label="Secret key name"
                 className="w-full bg-surface-sunken border border-line rounded px-2 py-1 text-[10px] font-mono text-ink focus:outline-none focus:border-accent" />
               <input value={newValue} onChange={(e) => setNewValue(e.target.value)} placeholder="Value" type="password"
+                aria-label="Secret value"
                 className="w-full bg-surface-sunken border border-line rounded px-2 py-1 text-[10px] text-ink focus:outline-none focus:border-accent" />
               <div className="flex gap-2">
                 <button type="button" onClick={() => { if (newKey && newValue) handleSave(newKey, newValue); }} disabled={!newKey || !newValue}

canvas/src/components/ui/TestConnectionButton.tsx

@@ -99,7 +99,7 @@ export function TestConnectionButton({
 
 function Spinner() {
   return (
-    <svg className="spinner" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <svg aria-hidden="true" className="spinner" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
       <path d="M12 2v4M12 18v4M4.93 4.93l2.83 2.83M16.24 16.24l2.83 2.83M2 12h4M18 12h4M4.93 19.07l2.83-2.83M16.24 7.76l2.83-2.83" />
     </svg>
   );

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

@@ -63,7 +63,7 @@ class MockWebSocket {
 (globalThis as unknown as Record<string, unknown>).WebSocket = MockWebSocket;
 
 // Now import the socket module (uses globalThis.WebSocket at call time)
-import { connectSocket, disconnectSocket } from "../socket";
+import { connectSocket, disconnectSocket, wakeSocket } from "../socket";
 import { useCanvasStore } from "../canvas";
 
 // ---------------------------------------------------------------------------
@@ -416,3 +416,84 @@ describe("RehydrateDedup", () => {
     expect(d.shouldSkip(2_700)).toBe(true);
   });
 });
+
+// ---------------------------------------------------------------------------
+// wakeSocket() — visibility-wake reconnect (regression #223 / #228)
+// ---------------------------------------------------------------------------
+//
+// Mobile browsers (iOS Safari, Chrome on Android in deep-sleep) silently
+// drop the WebSocket when the tab is backgrounded; the in-page onclose
+// fires very late or never. Without a visibility wake, the canvas stays
+// frozen until the user manually refreshes.
+//
+// The real wiring lives at module level: connectSocket installs a
+// visibilitychange/pageshow listener that calls wake() on foreground.
+// We can't dispatch DOM events here because the suite runs under the
+// `node` test environment (no `document`/`window` — see canvas/vitest
+// .config.ts). Instead we test wake() directly through the wakeSocket
+// public export, which is the same code path the listener invokes.
+
+describe("wakeSocket → reconnect (#223 / #228 — mobile visibility wake)", () => {
+  it("wake on a healthy OPEN socket does not create a new WebSocket", () => {
+    connectSocket();
+    const ws = getLastWS();
+    ws.triggerOpen();
+    // OPEN === 1. wake() should take the healthy-no-op branch.
+    (ws as unknown as { readyState: number }).readyState = 1;
+    const before = MockWebSocket.instances.length;
+    wakeSocket();
+    expect(MockWebSocket.instances.length).toBe(before);
+  });
+
+  it("wake on a CLOSED socket creates a new WebSocket (the actual #223 fix)", () => {
+    connectSocket();
+    const ws = getLastWS();
+    ws.triggerOpen();
+    // CLOSED === 3. Simulates the OS killing the socket while the tab
+    // was backgrounded. We deliberately don't fire triggerClose() —
+    // the whole point of #223 is that mobile browsers don't fire
+    // onclose when they kill the WS, so reconnect never schedules.
+    (ws as unknown as { readyState: number }).readyState = 3;
+    const before = MockWebSocket.instances.length;
+    wakeSocket();
+    expect(MockWebSocket.instances.length).toBe(before + 1);
+  });
+
+  it("wake while CONNECTING (readyState=0) does not pile another handshake", () => {
+    connectSocket();
+    const ws = getLastWS();
+    // CONNECTING === 0 — a handshake is already in flight.
+    (ws as unknown as { readyState: number }).readyState = 0;
+    const before = MockWebSocket.instances.length;
+    wakeSocket();
+    expect(MockWebSocket.instances.length).toBe(before);
+  });
+
+  it("wake cancels any pending backoff reconnect", () => {
+    const clearTimeoutSpy = vi.spyOn(globalThis, "clearTimeout");
+    connectSocket();
+    const ws = getLastWS();
+    ws.triggerOpen();
+    // Drop the socket — onclose schedules a backoff reconnect.
+    ws.triggerClose();
+    // Now wake the page. wake() should pre-empt the backoff so the
+    // user sees the canvas come back immediately, not after the
+    // exponential delay window.
+    (ws as unknown as { readyState: number }).readyState = 3;
+    clearTimeoutSpy.mockClear();
+    wakeSocket();
+    expect(clearTimeoutSpy).toHaveBeenCalled();
+    clearTimeoutSpy.mockRestore();
+  });
+
+  it("wake after disconnectSocket is a no-op (no zombie reconnect)", () => {
+    connectSocket();
+    const ws = getLastWS();
+    ws.triggerOpen();
+    disconnectSocket();
+    const before = MockWebSocket.instances.length;
+    // Singleton is null now — wake() should silently do nothing.
+    expect(() => wakeSocket()).not.toThrow();
+    expect(MockWebSocket.instances.length).toBe(before);
+  });
+});

canvas/src/store/socket.ts

@@ -268,6 +268,46 @@ class ReconnectingSocket {
     }
     useCanvasStore.getState().setWsStatus("disconnected");
   }
+
+  /** Force a reconnect attempt now, skipping the backoff window.
+   *  Used by the visibilitychange / pageshow handler: when a mobile
+   *  browser backgrounds the tab, the OS silently kills the WebSocket
+   *  but the in-page onclose either fires very late or never fires at
+   *  all (iOS Safari, Chrome on Android in deep-sleep). Once the user
+   *  brings the tab back, the canvas needs to reconnect within human
+   *  perception — not on whatever backoff delay was last scheduled,
+   *  which can be up to 30s. (#223 / #228)
+   *
+   *  Idempotent: if the socket is already OPEN we leave it alone; the
+   *  WebSocket is still healthy and a reconnect would just churn. */
+  wake() {
+    if (this.disposed) return;
+    // OPEN === 1. Use the numeric literal so we don't have to import
+    // WebSocket type values; the runtime constant is well-defined.
+    if (this.ws && this.ws.readyState === 1) {
+      // Healthy. Run a rehydrate to catch any events we may have missed
+      // while the tab was backgrounded — the OS does deliver some
+      // packets late, but it can also drop them, and the dedup gate
+      // collapses this with any subsequent health-check rehydrate.
+      void this.rehydrate();
+      return;
+    }
+    // CONNECTING === 0 means a handshake is already in flight. Don't
+    // pile another one on; the existing attempt or its onclose-driven
+    // reconnect will resolve.
+    if (this.ws && this.ws.readyState === 0) return;
+    // Otherwise (CLOSING, CLOSED, or null) we're in limbo. Cancel any
+    // pending backoff and reconnect now.
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    // Reset attempt counter so the *next* failure (if any) starts from
+    // a short delay again — we just had a real user interaction, not
+    // an unattended-tab failure cascade.
+    this.attempt = 0;
+    this.connect();
+  }
 }
 
 export interface WorkspaceData {
@@ -306,11 +346,49 @@ export interface WorkspaceData {
 
 let socket: ReconnectingSocket | null = null;
 
+/** visibilitychange / pageshow handler. Mobile browsers (iOS Safari,
+ *  Chrome on Android in deep-sleep) silently drop the WebSocket when
+ *  the tab is backgrounded — the in-page `onclose` fires very late or
+ *  never. Without this listener, the canvas appears frozen after the
+ *  user backgrounds the PWA and returns to it: status events, agent
+ *  messages, and cross-device chat broadcast don't arrive until a
+ *  manual refresh (#223 / #228).
+ *
+ *  Both events are wired: `visibilitychange` covers tab-switch on a
+ *  live page; `pageshow` covers Safari's bfcache restore, where the
+ *  page comes back from cache without firing visibilitychange. */
+function onPageWake() {
+  // document is undefined in SSR; the listener never installs there,
+  // but defensively guard anyway in case this code is run via a test
+  // harness that doesn't shim it.
+  if (typeof document !== "undefined" && document.hidden) return;
+  socket?.wake();
+}
+let visibilityHandlerInstalled = false;
+function installVisibilityHandler() {
+  if (visibilityHandlerInstalled) return;
+  if (typeof document === "undefined" || typeof window === "undefined") return;
+  document.addEventListener("visibilitychange", onPageWake);
+  // `pageshow` with `event.persisted === true` is the bfcache restore
+  // signal — relevant on iOS Safari. We don't need to inspect
+  // `persisted` because waking an OPEN socket is a no-op.
+  window.addEventListener("pageshow", onPageWake);
+  visibilityHandlerInstalled = true;
+}
+function uninstallVisibilityHandler() {
+  if (!visibilityHandlerInstalled) return;
+  if (typeof document === "undefined" || typeof window === "undefined") return;
+  document.removeEventListener("visibilitychange", onPageWake);
+  window.removeEventListener("pageshow", onPageWake);
+  visibilityHandlerInstalled = false;
+}
+
 export function connectSocket() {
   if (!socket) {
     socket = new ReconnectingSocket(WS_URL);
   }
   socket.connect();
+  installVisibilityHandler();
 }
 
 export function disconnectSocket() {
@@ -318,4 +396,14 @@ export function disconnectSocket() {
     socket.disconnect();
     socket = null;
   }
+  uninstallVisibilityHandler();
+}
+
+/** Manually trigger the visibility-wake path. Exported so the test suite
+ *  can exercise `ReconnectingSocket.wake()` without depending on a
+ *  jsdom DOM (the rest of this file's tests run under the node env).
+ *  Real-world callers don't need this — the visibility/pageshow listener
+ *  drives it. */
+export function wakeSocket() {
+  socket?.wake();
 }

canvas/src/styles/settings-panel.css

@@ -584,6 +584,10 @@
 .secrets-tab__refresh-btn:hover {
   background: #1e40af;
 }
+.secrets-tab__refresh-btn:focus-visible {
+  outline: 2px solid #1d4ed8;
+  outline-offset: 2px;
+}
 
 .secrets-tab__no-results {
   text-align: center;
@@ -649,6 +653,10 @@
   border-radius: 6px;
   cursor: pointer;
 }
+.delete-dialog__cancel-btn:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: var(--focus-ring-offset);
+}
 
 .delete-dialog__confirm-btn {
   background: var(--status-invalid);
@@ -658,6 +666,10 @@
   border-radius: 6px;
   cursor: pointer;
 }
+.delete-dialog__confirm-btn:focus-visible {
+  outline: var(--focus-ring);
+  outline-offset: var(--focus-ring-offset);
+}
 
 .delete-dialog__confirm-btn:disabled { opacity: 0.4; cursor: not-allowed; }
 

scripts/build_runtime_package.py

@@ -58,6 +58,7 @@ TOP_LEVEL_MODULES = {
     "a2a_response",
     "a2a_tools",
     "a2a_tools_delegation",
+    "a2a_tools_identity",
     "a2a_tools_inbox",
     "a2a_tools_memory",
     "a2a_tools_messaging",

workspace-server/cmd/t4-contract-dump/main.go

@@ -0,0 +1,35 @@
+// Command t4-contract-dump prints the T4 privilege contract as YAML.
+//
+// Usage:
+//
+//	go run ./workspace-server/cmd/t4-contract-dump > t4_capabilities.yaml
+//
+// This is the seam that template-repo CI workflows consume:
+//
+//	- Template CI fetches molecule-core at pinned ref
+//	- Runs `go run ./workspace-server/cmd/t4-contract-dump` to produce
+//	  t4_capabilities.yaml
+//	- Iterates capabilities and runs each Probe inside a freshly-built
+//	  privileged container
+//	- Aggregates structured pass/fail; fails the gate on any hard miss.
+//
+// Keeping this trivial and pure-stdlib means a fork user does not need
+// a Molecule-AI Gitea token or any internal infrastructure to consume
+// the contract — `go run` against molecule-core's public source is
+// enough.
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/Molecule-AI/molecule-monorepo/platform/internal/provisioner"
+)
+
+func main() {
+	caps := provisioner.T4PrivilegeContract()
+	if _, err := os.Stdout.WriteString(provisioner.AsYAML(caps)); err != nil {
+		fmt.Fprintln(os.Stderr, "t4-contract-dump: write failed:", err)
+		os.Exit(1)
+	}
+}

workspace-server/internal/handlers/agent_git_identity.go

@@ -17,6 +17,17 @@ var gitIdentitySlugPattern = regexp.MustCompile(`[^a-z0-9]+`)
 // docs/authorship.md (when it exists).
 const gitIdentityEmailDomain = "agents.moleculesai.app"
 
+// gitAskpassHelperPath is the in-container path of the askpass helper
+// installed by every workspace runtime image (workspace/Dockerfile in
+// molecule-core; scripts/git-askpass.sh → /usr/local/bin/molecule-askpass
+// in each external template-* repo). The helper reads GIT_HTTP_USERNAME
+// / GIT_HTTP_PASSWORD (falling back to GITEA_USER / GITEA_TOKEN) from
+// env and emits them on the git credential-prompt protocol. Setting
+// GIT_ASKPASS to this path is what wires container-side HTTPS git auth
+// to the persona credentials already arriving via workspace_secrets,
+// with no on-disk .gitconfig / .git-credentials mutation required.
+const gitAskpassHelperPath = "/usr/local/bin/molecule-askpass"
+
 // applyAgentGitIdentity sets GIT_AUTHOR_* / GIT_COMMITTER_* env vars so
 // every commit from this workspace container carries a distinct author
 // in `git log` and `git blame`. Git reads these env vars before falling
@@ -50,6 +61,34 @@ func applyAgentGitIdentity(envVars map[string]string, workspaceName string) {
 	setIfEmpty(envVars, "GIT_AUTHOR_EMAIL", authorEmail)
 	setIfEmpty(envVars, "GIT_COMMITTER_NAME", authorName)
 	setIfEmpty(envVars, "GIT_COMMITTER_EMAIL", authorEmail)
+
+	applyGitAskpass(envVars)
+}
+
+// applyGitAskpass points git at the in-image askpass helper so that any
+// HTTPS git operation against a remote without a pre-configured
+// credential.helper picks up the persona credentials already present in
+// the container env (GIT_HTTP_USERNAME / GIT_HTTP_PASSWORD, or
+// GITEA_USER / GITEA_TOKEN as fallback — the latter pair is what
+// loadPersonaEnvFile delivers from the operator-host bootstrap kit).
+//
+// Idempotent: if GIT_ASKPASS is already set (e.g. by an operator-
+// supplied workspace_secret or an env-mutator plugin), the existing
+// value wins. This lets a workspace opt out by setting GIT_ASKPASS=""
+// or pointing at a different helper.
+//
+// No vendor-specific behaviour lives in this function — the host the
+// credentials apply to is determined entirely by the deployer choosing
+// when to populate GIT_HTTP_USERNAME / GIT_HTTP_PASSWORD (or
+// GITEA_USER / GITEA_TOKEN). The helper script itself is generic and
+// has no hardcoded hostnames, so it's safe to ship inside the
+// open-source workspace template images alongside the platform-managed
+// claude-code image.
+func applyGitAskpass(envVars map[string]string) {
+	if envVars == nil {
+		return
+	}
+	setIfEmpty(envVars, "GIT_ASKPASS", gitAskpassHelperPath)
 }
 
 // slugifyForEmail collapses a workspace name to a safe email localpart:

workspace-server/internal/handlers/agent_git_identity_test.go

@@ -75,6 +75,53 @@ func TestApplyAgentGitIdentity_NilMapIsSafe(t *testing.T) {
 	applyAgentGitIdentity(nil, "PM")
 }
 
+func TestApplyAgentGitIdentity_SetsGitAskpass(t *testing.T) {
+	// GIT_ASKPASS is what wires container-side HTTPS git auth to the
+	// persona credentials (GITEA_USER/GITEA_TOKEN, etc.) that
+	// loadPersonaEnvFile delivers via workspace_secrets. Without this,
+	// `git push` inside the container would fall through to interactive
+	// prompts (impossible) or a missing credential.helper (401).
+	env := map[string]string{}
+	applyAgentGitIdentity(env, "Frontend Engineer")
+	if env["GIT_ASKPASS"] != "/usr/local/bin/molecule-askpass" {
+		t.Errorf("GIT_ASKPASS: got %q, want %q",
+			env["GIT_ASKPASS"], "/usr/local/bin/molecule-askpass")
+	}
+}
+
+func TestApplyAgentGitIdentity_RespectsAskpassOverride(t *testing.T) {
+	// A workspace_secret or env-mutator plugin must be able to point at
+	// a custom askpass helper without us clobbering it. Symmetric with
+	// the GIT_AUTHOR_NAME override test above.
+	env := map[string]string{
+		"GIT_ASKPASS": "/opt/custom/askpass",
+	}
+	applyAgentGitIdentity(env, "Backend Engineer")
+	if env["GIT_ASKPASS"] != "/opt/custom/askpass" {
+		t.Errorf("GIT_ASKPASS should not be overwritten, got %q", env["GIT_ASKPASS"])
+	}
+}
+
+func TestApplyAgentGitIdentity_AskpassSkippedOnEmptyName(t *testing.T) {
+	// The empty-name early-return covers GIT_ASKPASS too — a provisioning
+	// glitch that dropped the workspace name shouldn't half-configure the
+	// container (identity vars empty but askpass wired). All-or-nothing.
+	env := map[string]string{}
+	applyAgentGitIdentity(env, "")
+	if _, ok := env["GIT_ASKPASS"]; ok {
+		t.Errorf("empty name should not set GIT_ASKPASS, got %q", env["GIT_ASKPASS"])
+	}
+}
+
+func TestApplyGitAskpass_NilMapIsSafe(t *testing.T) {
+	defer func() {
+		if r := recover(); r != nil {
+			t.Errorf("applyGitAskpass panicked on nil map: %v", r)
+		}
+	}()
+	applyGitAskpass(nil)
+}
+
 func TestSlugifyForEmail(t *testing.T) {
 	cases := []struct {
 		in, want string

workspace-server/internal/handlers/external_connection.go

@@ -24,17 +24,30 @@ import (
 
 // BuildExternalConnectionPayload assembles the gin.H payload that the
 // canvas's ExternalConnectModal consumes. Pure data — caller owns DB
-// reads (workspace_id) and token minting (auth_token).
+// reads (workspace_id, workspace_name) and token minting (auth_token).
 //
 // authToken may be empty for the read-only "show instructions again"
 // path; the modal masks the field in that case rather than displaying
 // an empty string.
-func BuildExternalConnectionPayload(platformURL, workspaceID, authToken string) gin.H {
+//
+// workspaceName feeds the per-workspace MCP server-name in the snippets
+// that wire molecule-mcp into an external Claude Code (or other
+// MCP-stdio) client. Without a unique server name a second
+// `claude mcp add molecule` call REPLACES the first entry, collapsing
+// multi-workspace use into a single per-session slot — see
+// mcpServerNameForWorkspace below. May be empty (re-show / rotate paths
+// that don't plumb the name); the helper falls back to the workspace
+// ID's short prefix so the snippet is always unique.
+func BuildExternalConnectionPayload(platformURL, workspaceID, workspaceName, authToken string) gin.H {
 	pURL := strings.TrimSuffix(platformURL, "/")
+	mcpName := mcpServerNameForWorkspace(workspaceID, workspaceName)
 	stamp := func(tmpl string) string {
 		return strings.ReplaceAll(
-			strings.ReplaceAll(tmpl, "{{PLATFORM_URL}}", pURL),
-			"{{WORKSPACE_ID}}", workspaceID,
+			strings.ReplaceAll(
+				strings.ReplaceAll(tmpl, "{{PLATFORM_URL}}", pURL),
+				"{{WORKSPACE_ID}}", workspaceID,
+			),
+			"{{MCP_SERVER_NAME}}", mcpName,
 		)
 	}
 	return gin.H{
@@ -77,6 +90,81 @@ func externalPlatformURL(c *gin.Context) string {
 	return scheme + "://" + host
 }
 
+// mcpServerNameForWorkspace derives the unique MCP server name used in
+// the Universal MCP snippet's `claude mcp add <name> -- ...` line.
+//
+// Why per-workspace, not a fixed "molecule": `claude mcp add` keys
+// entries by name in ~/.claude.json, so re-running with the same name
+// silently REPLACES the previous entry. A single external Claude Code
+// session that connects to N molecule workspaces must therefore use N
+// distinct server names — otherwise the second install collapses the
+// first, and the user experiences "MCP is per-session". MCP itself
+// supports many servers per session; the install-snippet name was the
+// only thing standing in the way.
+//
+// Pattern: "molecule-<slug>" where slug comes from the workspace name
+// (lowercased, non-alphanumeric → hyphen, collapsed, trimmed, <=24
+// chars). Falls back to the workspace ID's first 8 chars when the name
+// is empty or slugifies to nothing — both produce a deterministic,
+// Claude-Code-name-safe (alphanumeric + hyphens, no spaces / dots /
+// slashes) identifier that disambiguates per-workspace.
+//
+// Two workspaces with identical names still produce identical slugs by
+// design — the user picked them to look the same. The
+// `claude mcp add` step will overwrite the older one in that case;
+// the workaround is to rename one, then re-run. Documented in the
+// snippet header so users aren't surprised.
+func mcpServerNameForWorkspace(workspaceID, workspaceName string) string {
+	const fallbackIDPrefixLen = 8
+	const maxSlugLen = 24
+	slug := slugifyForMcpName(workspaceName, maxSlugLen)
+	if slug == "" {
+		id := strings.ReplaceAll(workspaceID, "-", "")
+		if len(id) > fallbackIDPrefixLen {
+			id = id[:fallbackIDPrefixLen]
+		}
+		slug = id
+	}
+	if slug == "" {
+		// Defensive: empty workspaceID at this layer means the caller
+		// is misusing the API; we still return a usable (non-colliding
+		// in the common case) constant rather than producing "molecule-"
+		// which Claude Code would reject.
+		return "molecule"
+	}
+	return "molecule-" + slug
+}
+
+// slugifyForMcpName lowercases, replaces non-[a-z0-9] runs with a single
+// '-', trims leading/trailing '-', and truncates to maxLen. Returns ""
+// if nothing usable remains. Pure helper; no allocations beyond the
+// builder.
+func slugifyForMcpName(s string, maxLen int) string {
+	var b strings.Builder
+	b.Grow(len(s))
+	lastHyphen := true // suppress leading hyphens
+	for _, r := range s {
+		switch {
+		case r >= 'A' && r <= 'Z':
+			b.WriteRune(r + ('a' - 'A'))
+			lastHyphen = false
+		case (r >= 'a' && r <= 'z') || (r >= '0' && r <= '9'):
+			b.WriteRune(r)
+			lastHyphen = false
+		default:
+			if !lastHyphen {
+				b.WriteByte('-')
+				lastHyphen = true
+			}
+		}
+	}
+	out := strings.TrimRight(b.String(), "-")
+	if len(out) > maxLen {
+		out = strings.TrimRight(out[:maxLen], "-")
+	}
+	return out
+}
+
 // externalCurlTemplate — zero-dependency register snippet. Placeholders:
 //   - {{PLATFORM_URL}}, {{WORKSPACE_ID}}   — filled server-side
 //   - $WORKSPACE_AUTH_TOKEN                — env var, operator sets
@@ -216,6 +304,14 @@ const externalUniversalMcpTemplate = `# Universal MCP — standalone register +
 # for any MCP-aware runtime (Claude Code, hermes, codex, etc.).
 # Pair with the Claude Code or Python SDK tab if your runtime needs
 # inbound A2A delivery (canvas messages → agent conversation turns).
+#
+# Multi-workspace: MCP supports many servers per Claude Code session.
+# This snippet uses a workspace-specific server name ({{MCP_SERVER_NAME}})
+# so installing for a second workspace ADDS another entry instead of
+# overwriting the first — run the snippet from each workspace's modal
+# in turn and ` + "`claude mcp list`" + ` will show all of them. If two
+# workspaces have the same name, slugs collide and the second install
+# overwrites the first; rename one workspace to disambiguate.
 
 # Requires Python >= 3.11. On 3.10 or older pip says
 # "Could not find a version that satisfies the requirement
@@ -224,11 +320,14 @@ const externalUniversalMcpTemplate = `# Universal MCP — standalone register +
 # Upgrade the interpreter (brew install python@3.12 / apt install
 # python3.12 / etc.) or use a 3.11+ venv.
 
-# 1. Install the workspace runtime wheel:
+# 1. Install the workspace runtime wheel (once per machine — safe to
+#    re-run; subsequent workspaces share the same wheel):
 pip install molecule-ai-workspace-runtime
 
 # 2. Wire molecule-mcp into your agent's MCP config. Claude Code:
-claude mcp add molecule -s user -- env \
+#    NOTE the server name is workspace-specific ("{{MCP_SERVER_NAME}}") so
+#    multiple molecule workspaces co-exist in one Claude Code session.
+claude mcp add {{MCP_SERVER_NAME}} -s user -- env \
   WORKSPACE_ID={{WORKSPACE_ID}} \
   PLATFORM_URL={{PLATFORM_URL}} \
   MOLECULE_WORKSPACE_TOKEN="<paste from create response>" \
@@ -249,8 +348,11 @@ claude mcp add molecule -s user -- env \
 #   Documentation: https://doc.moleculesai.app/docs/guides/mcp-server-setup
 #   Common errors:
 #     • "Tools not appearing in your agent" — run ` + "`claude mcp list`" + ` (or
-#       your runtime's equivalent) and confirm the molecule entry. If
-#       missing, re-run the ` + "`claude mcp add`" + ` line above.
+#       your runtime's equivalent) and confirm the {{MCP_SERVER_NAME}} entry.
+#       If missing, re-run the ` + "`claude mcp add`" + ` line above.
+#     • "Connecting a second workspace overwrote the first" — re-check that
+#       the server name in the line above is {{MCP_SERVER_NAME}} (not a bare
+#       "molecule"); each workspace's modal generates a distinct name.
 #     • "ConnectionRefused / DNS error on first call" — PLATFORM_URL must
 #       include the scheme (https://) and have NO trailing slash. Verify
 #       with: curl ${PLATFORM_URL}/healthz

workspace-server/internal/handlers/external_rotate.go

@@ -52,7 +52,7 @@ func (h *WorkspaceHandler) RotateExternalCredentials(c *gin.Context) {
 	}
 	ctx := c.Request.Context()
 
-	runtime, err := lookupWorkspaceRuntime(ctx, db.DB, id)
+	runtime, name, err := lookupWorkspaceRuntimeAndName(ctx, db.DB, id)
 	if errors.Is(err, sql.ErrNoRows) {
 		c.JSON(http.StatusNotFound, gin.H{"error": "workspace not found"})
 		return
@@ -108,7 +108,7 @@ func (h *WorkspaceHandler) RotateExternalCredentials(c *gin.Context) {
 
 	platformURL := externalPlatformURL(c)
 	c.JSON(http.StatusOK, gin.H{
-		"connection": BuildExternalConnectionPayload(platformURL, id, tok),
+		"connection": BuildExternalConnectionPayload(platformURL, id, name, tok),
 	})
 }
 
@@ -129,7 +129,7 @@ func (h *WorkspaceHandler) GetExternalConnection(c *gin.Context) {
 	}
 	ctx := c.Request.Context()
 
-	runtime, err := lookupWorkspaceRuntime(ctx, db.DB, id)
+	runtime, name, err := lookupWorkspaceRuntimeAndName(ctx, db.DB, id)
 	if errors.Is(err, sql.ErrNoRows) {
 		c.JSON(http.StatusNotFound, gin.H{"error": "workspace not found"})
 		return
@@ -149,16 +149,20 @@ func (h *WorkspaceHandler) GetExternalConnection(c *gin.Context) {
 
 	platformURL := externalPlatformURL(c)
 	c.JSON(http.StatusOK, gin.H{
-		"connection": BuildExternalConnectionPayload(platformURL, id, ""),
+		"connection": BuildExternalConnectionPayload(platformURL, id, name, ""),
 	})
 }
 
-// lookupWorkspaceRuntime returns the workspace's runtime field. Wrapped
-// for readability + so tests can mock the single SELECT.
-func lookupWorkspaceRuntime(ctx context.Context, handle *sql.DB, id string) (string, error) {
-	var runtime string
-	err := handle.QueryRowContext(ctx, `
-		SELECT COALESCE(runtime, '') FROM workspaces WHERE id = $1
-	`, id).Scan(&runtime)
-	return runtime, err
+// lookupWorkspaceRuntimeAndName returns runtime + name in one round-trip.
+// Wrapped for readability + so tests can mock the single SELECT.
+// Used by rotate / re-show paths: runtime gates the external-only check;
+// name feeds the per-workspace MCP server slug in BuildExternalConnectionPayload
+// (so the Universal MCP snippet uses a stable per-workspace name instead
+// of overwriting prior `claude mcp add molecule` entries).
+// Returns sql.ErrNoRows when the workspace doesn't exist.
+func lookupWorkspaceRuntimeAndName(ctx context.Context, handle *sql.DB, id string) (runtime, name string, err error) {
+	err = handle.QueryRowContext(ctx, `
+		SELECT COALESCE(runtime, ''), COALESCE(name, '') FROM workspaces WHERE id = $1
+	`, id).Scan(&runtime, &name)
+	return runtime, name, err
 }

workspace-server/internal/handlers/external_rotate_test.go

@@ -35,9 +35,9 @@ func TestRotateExternalCredentials_HappyPath(t *testing.T) {
 	wh := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
 
 	// 1. Runtime lookup
-	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\) FROM workspaces WHERE id = \$1`).
+	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\), COALESCE\(name, ''\) FROM workspaces WHERE id = \$1`).
 		WithArgs("ws-ext").
-		WillReturnRows(sqlmock.NewRows([]string{"runtime"}).AddRow("external"))
+		WillReturnRows(sqlmock.NewRows([]string{"runtime", "name"}).AddRow("external", "test-ws"))
 
 	// 2. Revoke all live tokens
 	mock.ExpectExec(`UPDATE workspace_auth_tokens`).
@@ -98,9 +98,9 @@ func TestRotateExternalCredentials_RejectsNonExternal(t *testing.T) {
 	setupTestRedis(t)
 	wh := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
 
-	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\) FROM workspaces WHERE id = \$1`).
+	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\), COALESCE\(name, ''\) FROM workspaces WHERE id = \$1`).
 		WithArgs("ws-hermes").
-		WillReturnRows(sqlmock.NewRows([]string{"runtime"}).AddRow("hermes"))
+		WillReturnRows(sqlmock.NewRows([]string{"runtime", "name"}).AddRow("hermes", "test-ws"))
 
 	w := httptest.NewRecorder()
 	c, _ := gin.CreateTestContext(w)
@@ -129,9 +129,9 @@ func TestRotateExternalCredentials_NotFound(t *testing.T) {
 	setupTestRedis(t)
 	wh := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
 
-	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\) FROM workspaces WHERE id = \$1`).
+	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\), COALESCE\(name, ''\) FROM workspaces WHERE id = \$1`).
 		WithArgs("ws-missing").
-		WillReturnRows(sqlmock.NewRows([]string{"runtime"})) // no rows
+		WillReturnRows(sqlmock.NewRows([]string{"runtime", "name"})) // no rows
 
 	w := httptest.NewRecorder()
 	c, _ := gin.CreateTestContext(w)
@@ -172,9 +172,9 @@ func TestGetExternalConnection_HappyPathReturnsBlankToken(t *testing.T) {
 	setupTestRedis(t)
 	wh := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
 
-	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\) FROM workspaces WHERE id = \$1`).
+	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\), COALESCE\(name, ''\) FROM workspaces WHERE id = \$1`).
 		WithArgs("ws-ext").
-		WillReturnRows(sqlmock.NewRows([]string{"runtime"}).AddRow("external"))
+		WillReturnRows(sqlmock.NewRows([]string{"runtime", "name"}).AddRow("external", "test-ws"))
 
 	w := httptest.NewRecorder()
 	c, _ := gin.CreateTestContext(w)
@@ -211,9 +211,9 @@ func TestGetExternalConnection_RejectsNonExternal(t *testing.T) {
 	setupTestRedis(t)
 	wh := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
 
-	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\) FROM workspaces WHERE id = \$1`).
+	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\), COALESCE\(name, ''\) FROM workspaces WHERE id = \$1`).
 		WithArgs("ws-claude").
-		WillReturnRows(sqlmock.NewRows([]string{"runtime"}).AddRow("claude-code"))
+		WillReturnRows(sqlmock.NewRows([]string{"runtime", "name"}).AddRow("claude-code", "test-ws"))
 
 	w := httptest.NewRecorder()
 	c, _ := gin.CreateTestContext(w)
@@ -233,9 +233,9 @@ func TestGetExternalConnection_NotFound(t *testing.T) {
 	setupTestRedis(t)
 	wh := NewWorkspaceHandler(newTestBroadcaster(), nil, "http://localhost:8080", t.TempDir())
 
-	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\) FROM workspaces WHERE id = \$1`).
+	mock.ExpectQuery(`SELECT COALESCE\(runtime, ''\), COALESCE\(name, ''\) FROM workspaces WHERE id = \$1`).
 		WithArgs("ws-missing").
-		WillReturnRows(sqlmock.NewRows([]string{"runtime"}))
+		WillReturnRows(sqlmock.NewRows([]string{"runtime", "name"}))
 
 	w := httptest.NewRecorder()
 	c, _ := gin.CreateTestContext(w)
@@ -253,7 +253,7 @@ func TestGetExternalConnection_NotFound(t *testing.T) {
 // ---------- BuildExternalConnectionPayload (pure helper) ----------
 
 func TestBuildExternalConnectionPayload_StampsPlaceholders(t *testing.T) {
-	got := BuildExternalConnectionPayload("https://platform.test", "ws-7", "tok-abc")
+	got := BuildExternalConnectionPayload("https://platform.test", "ws-7", "my-bot", "tok-abc")
 
 	if got["workspace_id"] != "ws-7" {
 		t.Errorf("workspace_id: %v", got["workspace_id"])
@@ -267,6 +267,18 @@ func TestBuildExternalConnectionPayload_StampsPlaceholders(t *testing.T) {
 	if got["registry_endpoint"] != "https://platform.test/registry/register" {
 		t.Errorf("registry_endpoint: %v", got["registry_endpoint"])
 	}
+	// Universal MCP snippet must contain a workspace-specific server
+	// name derived from the workspace name. Without this each new
+	// `claude mcp add` would overwrite the previous entry in the user's
+	// ~/.claude.json (servers are keyed by name) — collapsing
+	// multi-workspace use into one slot. See mcpServerNameForWorkspace.
+	mcp, _ := got["universal_mcp_snippet"].(string)
+	if !strings.Contains(mcp, "claude mcp add molecule-my-bot ") {
+		t.Errorf("universal_mcp_snippet missing per-workspace server name 'molecule-my-bot':\n%s", mcp)
+	}
+	if strings.Contains(mcp, "{{MCP_SERVER_NAME}}") {
+		t.Errorf("universal_mcp_snippet still contains literal {{MCP_SERVER_NAME}}")
+	}
 	// {{PLATFORM_URL}} + {{WORKSPACE_ID}} placeholders must be substituted
 	// out of every snippet — if any snippet still contains a literal
 	// "{{PLATFORM_URL}}" or "{{WORKSPACE_ID}}", a future template author
@@ -292,7 +304,7 @@ func TestBuildExternalConnectionPayload_TrimsTrailingSlash(t *testing.T) {
 	// being concatenated into endpoint paths — otherwise the operator
 	// gets `https://platform.test//registry/register` (double slash) which
 	// some servers reject as a redirect target.
-	got := BuildExternalConnectionPayload("https://platform.test/", "ws-7", "")
+	got := BuildExternalConnectionPayload("https://platform.test/", "ws-7", "", "")
 	if got["platform_url"] != "https://platform.test" {
 		t.Errorf("platform_url: trailing slash not trimmed; got %v", got["platform_url"])
 	}
@@ -304,8 +316,48 @@ func TestBuildExternalConnectionPayload_TrimsTrailingSlash(t *testing.T) {
 func TestBuildExternalConnectionPayload_BlankAuthTokenIsAllowed(t *testing.T) {
 	// Re-show path: auth_token="" is the contract; the modal masks the
 	// field and labels it "rotate to reveal a new token".
-	got := BuildExternalConnectionPayload("https://platform.test", "ws-7", "")
+	got := BuildExternalConnectionPayload("https://platform.test", "ws-7", "", "")
 	if got["auth_token"] != "" {
 		t.Errorf("blank token must propagate as \"\"; got %v", got["auth_token"])
 	}
 }
+
+// TestBuildExternalConnectionPayload_McpServerNameUniquePerWorkspace
+// pins the multi-workspace install contract: two distinct workspaces
+// must produce two distinct `claude mcp add` server-name lines, or
+// installing the second one will overwrite the first entry in the
+// user's ~/.claude.json (servers are keyed by name) — collapsing
+// multi-workspace use into a single per-session slot, which is the
+// "this is per-session" UX the CTO observed 2026-05-18.
+func TestBuildExternalConnectionPayload_McpServerNameUniquePerWorkspace(t *testing.T) {
+	cases := []struct {
+		name        string
+		workspaceID string
+		wsName      string
+		wantAddLine string // must appear in universal_mcp_snippet
+	}{
+		{"plain name", "id-a", "my-bot", "claude mcp add molecule-my-bot "},
+		{"name with spaces + caps", "id-b", "My Bot 1", "claude mcp add molecule-my-bot-1 "},
+		// Symbol/punctuation collapses to single hyphens and trims.
+		{"name with symbols", "id-c", "--Foo!!Bar--", "claude mcp add molecule-foo-bar "},
+		// Empty name falls back to the first 8 chars of the (de-hyphenated)
+		// workspace UUID — keeps the snippet unique per workspace even
+		// when callers (rotate/re-show pre-name-lookup) pass "".
+		{"empty name, uuid id", "12345678-aaaa-bbbb-cccc-deadbeef0000", "", "claude mcp add molecule-12345678 "},
+	}
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := BuildExternalConnectionPayload("https://p.test", tc.workspaceID, tc.wsName, "tok")
+			mcp, _ := got["universal_mcp_snippet"].(string)
+			if !strings.Contains(mcp, tc.wantAddLine) {
+				t.Errorf("missing %q in universal_mcp_snippet:\n%s", tc.wantAddLine, mcp)
+			}
+			// Belt + suspenders: never the bare fixed `molecule` name —
+			// that was the bug. (Match with trailing space so the
+			// "molecule-…" form passes.)
+			if strings.Contains(mcp, "claude mcp add molecule ") {
+				t.Errorf("snippet regressed to fixed `claude mcp add molecule `; got:\n%s", mcp)
+			}
+		})
+	}
+}

workspace-server/internal/handlers/org_helpers.go

@@ -218,6 +218,14 @@ func loadWorkspaceEnv(orgBaseDir, filesDir string) map[string]string {
 // check, or when the env file does not exist (workspaces without a role —
 // or running on hosts that don't ship the bootstrap dir — keep their old
 // behavior).
+//
+// Token-file fallback: the newer prod-team personas (agent-dev-a,
+// agent-dev-b, agent-pm) ship `token` + `universal-auth.env` only — no
+// legacy plaintext `env` file. When the env-file load produces zero rows,
+// loadPersonaTokenFile fills in GITEA_TOKEN / GITEA_USER / GITEA_USER_EMAIL
+// from the token file so the GIT_ASKPASS helper has something to emit.
+// The env-file form remains authoritative when present (it may carry
+// richer rows like GITEA_TOKEN_SCOPES / GITEA_SSH_KEY_PATH).
 func loadPersonaEnvFile(role string, out map[string]string) {
 	if !isSafeRoleName(role) {
 		if role != "" {
@@ -229,7 +237,61 @@ func loadPersonaEnvFile(role string, out map[string]string) {
 	if root == "" {
 		root = "/etc/molecule-bootstrap/personas"
 	}
+	before := len(out)
 	parseEnvFile(filepath.Join(root, role, "env"), out)
+	if len(out) == before {
+		// No env-file rows landed (file absent, or present-but-empty).
+		// Try the token-only persona shape used by the prod-team
+		// identities. Existing keys in out are preserved.
+		loadPersonaTokenFile(role, out)
+	}
+}
+
+// loadPersonaTokenFile populates GITEA_TOKEN / GITEA_USER / GITEA_USER_EMAIL
+// from a persona dir that ships only the bare `token` file — the shape used
+// by the production agent personas (agent-dev-a, agent-dev-b, agent-pm).
+// Those dirs do not carry an `env` file because their non-Gitea creds come
+// from Infisical Universal Auth at runtime (universal-auth.env), so the
+// historical loadPersonaEnvFile path silently no-ops on them.
+//
+// File layout: $MOLECULE_PERSONA_ROOT/<role>/token (mode 600, plain text).
+// The token contents become GITEA_TOKEN (whitespace-trimmed); the role
+// name becomes GITEA_USER; GITEA_USER_EMAIL is synthesised as
+// <role>@<gitIdentityEmailDomain> to match the email shape that
+// applyAgentGitIdentity uses for its slug-derived authorship addresses.
+//
+// Silent no-op when the role fails the safe-segment check, when the
+// token file does not exist, or when its contents are empty after
+// trimming. Existing keys in out are not overwritten — the caller's
+// later .env layers and any prior loadPersonaEnvFile rows always win.
+func loadPersonaTokenFile(role string, out map[string]string) {
+	if out == nil {
+		return
+	}
+	if !isSafeRoleName(role) {
+		return
+	}
+	root := os.Getenv("MOLECULE_PERSONA_ROOT")
+	if root == "" {
+		root = "/etc/molecule-bootstrap/personas"
+	}
+	data, err := os.ReadFile(filepath.Join(root, role, "token"))
+	if err != nil {
+		return
+	}
+	token := strings.TrimSpace(string(data))
+	if token == "" {
+		return
+	}
+	if _, ok := out["GITEA_TOKEN"]; !ok {
+		out["GITEA_TOKEN"] = token
+	}
+	if _, ok := out["GITEA_USER"]; !ok {
+		out["GITEA_USER"] = role
+	}
+	if _, ok := out["GITEA_USER_EMAIL"]; !ok {
+		out["GITEA_USER_EMAIL"] = role + "@" + gitIdentityEmailDomain
+	}
 }
 
 // isSafeRoleName accepts a single path segment of [A-Za-z0-9_-]+. Rejects

workspace-server/internal/handlers/org_persona_env_test.go

@@ -164,3 +164,181 @@ func TestIsSafeRoleName_Acceptance(t *testing.T) {
 		}
 	}
 }
+
+// TestLoadPersonaTokenFile_TokenOnlyPersona: the prod-team personas
+// (agent-dev-a / agent-dev-b / agent-pm) ship `token` only — no `env`
+// file. loadPersonaEnvFile's fallback path must populate GITEA_TOKEN /
+// GITEA_USER / GITEA_USER_EMAIL from the token contents + role name so
+// the GIT_ASKPASS helper has something to emit.
+func TestLoadPersonaTokenFile_TokenOnlyPersona(t *testing.T) {
+	root := t.TempDir()
+	roleDir := filepath.Join(root, "agent-dev-a")
+	if err := os.MkdirAll(roleDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(roleDir, "token"),
+		[]byte("token-bytes-redacted\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("MOLECULE_PERSONA_ROOT", root)
+
+	out := map[string]string{}
+	loadPersonaEnvFile("agent-dev-a", out)
+
+	want := map[string]string{
+		"GITEA_TOKEN":      "token-bytes-redacted",
+		"GITEA_USER":       "agent-dev-a",
+		"GITEA_USER_EMAIL": "agent-dev-a@" + gitIdentityEmailDomain,
+	}
+	if len(out) != len(want) {
+		t.Fatalf("got %d keys, want %d: %#v", len(out), len(want), out)
+	}
+	for k, v := range want {
+		if out[k] != v {
+			t.Errorf("out[%q] = %q; want %q", k, out[k], v)
+		}
+	}
+}
+
+// TestLoadPersonaTokenFile_EnvFileWins: when BOTH an env file and a
+// token file exist in the same persona dir, the env file is the more-
+// specific declaration and wins outright — the fallback must not fire
+// at all. This pins precedence so a persona later migrated to the
+// richer env-file form (carrying GITEA_TOKEN_SCOPES / GITEA_SSH_KEY_PATH)
+// doesn't get its token silently overridden by the fallback.
+func TestLoadPersonaTokenFile_EnvFileWins(t *testing.T) {
+	root := t.TempDir()
+	roleDir := filepath.Join(root, "agent-dev-b")
+	if err := os.MkdirAll(roleDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	envBody := "GITEA_USER=env-form-user\nGITEA_TOKEN=env-form-token\n" +
+		"GITEA_USER_EMAIL=env-form@example.invalid\nGITEA_TOKEN_SCOPES=write:repository\n"
+	if err := os.WriteFile(filepath.Join(roleDir, "env"), []byte(envBody), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(roleDir, "token"),
+		[]byte("token-form-token\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("MOLECULE_PERSONA_ROOT", root)
+
+	out := map[string]string{}
+	loadPersonaEnvFile("agent-dev-b", out)
+
+	if out["GITEA_USER"] != "env-form-user" {
+		t.Errorf("env file should win for GITEA_USER; got %q", out["GITEA_USER"])
+	}
+	if out["GITEA_TOKEN"] != "env-form-token" {
+		t.Errorf("env file should win for GITEA_TOKEN; got %q", out["GITEA_TOKEN"])
+	}
+	if out["GITEA_USER_EMAIL"] != "env-form@example.invalid" {
+		t.Errorf("env file should win for GITEA_USER_EMAIL; got %q", out["GITEA_USER_EMAIL"])
+	}
+	if out["GITEA_TOKEN_SCOPES"] != "write:repository" {
+		t.Errorf("env file extras must be preserved; got GITEA_TOKEN_SCOPES=%q", out["GITEA_TOKEN_SCOPES"])
+	}
+}
+
+// TestLoadPersonaTokenFile_NeitherFile: persona dir exists but ships
+// neither env nor token — silent no-op. This is the legitimate case
+// for a partially-provisioned persona during bootstrap; callers expect
+// an empty map, no error, no log noise.
+func TestLoadPersonaTokenFile_NeitherFile(t *testing.T) {
+	root := t.TempDir()
+	roleDir := filepath.Join(root, "agent-pm")
+	if err := os.MkdirAll(roleDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("MOLECULE_PERSONA_ROOT", root)
+
+	out := map[string]string{}
+	loadPersonaEnvFile("agent-pm", out)
+	if len(out) != 0 {
+		t.Errorf("expected empty out when neither env nor token exists; got %#v", out)
+	}
+}
+
+// TestLoadPersonaTokenFile_EmptyToken: a token file with only
+// whitespace must be treated as absent — never emit
+// GITEA_TOKEN="" / GITEA_USER=<role> / GITEA_USER_EMAIL=<role>@... because
+// that would set GITEA_USER without a usable token, and the askpass
+// helper would then prompt with an empty password. Silent no-op is the
+// correct behavior — let downstream auth fall through to its existing
+// "no credentials available" path.
+func TestLoadPersonaTokenFile_EmptyToken(t *testing.T) {
+	root := t.TempDir()
+	roleDir := filepath.Join(root, "agent-dev-a")
+	if err := os.MkdirAll(roleDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	// Whitespace-only contents: spaces, tabs, newlines.
+	if err := os.WriteFile(filepath.Join(roleDir, "token"),
+		[]byte("   \t\n  \n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("MOLECULE_PERSONA_ROOT", root)
+
+	out := map[string]string{}
+	loadPersonaEnvFile("agent-dev-a", out)
+	if len(out) != 0 {
+		t.Errorf("expected empty out when token file is whitespace-only; got %#v", out)
+	}
+}
+
+// TestLoadPersonaTokenFile_TrimsWhitespace: tokens shipped from the
+// operator-host bootstrap kit may have a trailing newline (the
+// canonical `printf "%s\n" "$token" > token` shape). The fallback must
+// trim leading + trailing whitespace so the askpass helper emits the
+// raw token bytes — Gitea's PAT validator rejects tokens with embedded
+// whitespace.
+func TestLoadPersonaTokenFile_TrimsWhitespace(t *testing.T) {
+	root := t.TempDir()
+	roleDir := filepath.Join(root, "agent-dev-b")
+	if err := os.MkdirAll(roleDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(roleDir, "token"),
+		[]byte("\n  raw-token-bytes  \n\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("MOLECULE_PERSONA_ROOT", root)
+
+	out := map[string]string{}
+	loadPersonaEnvFile("agent-dev-b", out)
+	if out["GITEA_TOKEN"] != "raw-token-bytes" {
+		t.Errorf("token whitespace not trimmed; got %q", out["GITEA_TOKEN"])
+	}
+}
+
+// TestLoadPersonaTokenFile_RejectsUnsafeRole: defense-in-depth — even
+// in the fallback path, role names that fail isSafeRoleName must not
+// touch the filesystem. Mirrors TestLoadPersonaEnvFile_RejectsTraversal.
+func TestLoadPersonaTokenFile_RejectsUnsafeRole(t *testing.T) {
+	root := t.TempDir()
+	// Plant a token at /tmp/.../token so a bad traversal would reach it.
+	if err := os.WriteFile(filepath.Join(root, "token"),
+		[]byte("stolen-token\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	t.Setenv("MOLECULE_PERSONA_ROOT", filepath.Join(root, "personas"))
+
+	for _, bad := range []string{"..", "../personas", "/abs", "with/slash", "."} {
+		out := map[string]string{}
+		loadPersonaTokenFile(bad, out)
+		if len(out) != 0 {
+			t.Errorf("role %q should have been rejected; got %#v", bad, out)
+		}
+	}
+}
+
+// TestLoadPersonaTokenFile_NilMapSafe: callers pass a fresh map in
+// practice, but defense-in-depth — a nil map must not panic.
+func TestLoadPersonaTokenFile_NilMapSafe(t *testing.T) {
+	defer func() {
+		if r := recover(); r != nil {
+			t.Fatalf("nil map caused panic: %v", r)
+		}
+	}()
+	loadPersonaTokenFile("agent-dev-a", nil)
+}

workspace-server/internal/handlers/workspace.go

@@ -198,6 +198,17 @@ func (h *WorkspaceHandler) Create(c *gin.Context) {
 	// back to its compiled-in Anthropic default and 401s when the user's
 	// key is for a different provider. Non-hermes runtimes are unaffected
 	// (the server still passes model through, they just don't use it).
+	// runtimeExplicitlyRequested is true when the caller expressed intent for
+	// a SPECIFIC runtime — either by passing `runtime` directly, or by naming
+	// a `template` (a template encodes a runtime). When true, we must NOT
+	// silently fall back to langgraph if that intent can't be honored: that
+	// is the molecule-controlplane#188 / #184 contract violation (caller asks
+	// for codex/claude-code, gets a langgraph workspace, 201, no error — a
+	// false success). #188 mandates fail-closed (error+notify) on mismatch,
+	// not an advisory degrade. The legitimate "no template, no runtime →
+	// langgraph default" path (bare {"name":...}) is unaffected.
+	runtimeExplicitlyRequested := payload.Runtime != "" || payload.Template != ""
+	templateRuntimeResolved := payload.Runtime != ""
 	if payload.Template != "" && (payload.Runtime == "" || payload.Model == "") {
 		// #226: payload.Template is attacker-controllable. resolveInsideRoot
 		// rejects absolute paths and any ".." that escapes configsDir so the
@@ -230,6 +241,9 @@ func (h *WorkspaceHandler) Create(c *gin.Context) {
 			switch {
 			case payload.Runtime == "" && !indented && strings.HasPrefix(stripped, "runtime:") && !strings.HasPrefix(stripped, "runtime_config"):
 				payload.Runtime = strings.TrimSpace(strings.TrimPrefix(stripped, "runtime:"))
+				if payload.Runtime != "" {
+					templateRuntimeResolved = true
+				}
 			case payload.Model == "" && !indented && strings.HasPrefix(stripped, "model:"):
 				// Legacy top-level `model:` — pre-runtime_config templates.
 				payload.Model = strings.Trim(strings.TrimSpace(strings.TrimPrefix(stripped, "model:")), `"'`)
@@ -242,7 +256,27 @@ func (h *WorkspaceHandler) Create(c *gin.Context) {
 			}
 		}
 	}
+	// Fail-closed (molecule-controlplane#188 / #184): if the caller expressed
+	// intent for a specific runtime (passed `runtime`, or named a `template`)
+	// but we could NOT resolve a concrete runtime from it (template's
+	// config.yaml unreadable, or it has no `runtime:` key), DO NOT silently
+	// substitute langgraph and return 201 — that is the silent contract
+	// violation that produced 5/5 wrong workspaces and a false codex E2E pass.
+	// Return 422 so the caller learns the requested runtime was not honored.
+	// The platform-side CP fix (controlplane#188) is the sibling gate; this
+	// closes the ws-server `Create` boundary the product UI actually hits.
+	if payload.Runtime == "" && runtimeExplicitlyRequested && !templateRuntimeResolved {
+		log.Printf("Create: FAIL-CLOSED (controlplane#188) — template=%q requested but runtime could not be resolved; refusing silent langgraph fallback", payload.Template)
+		c.JSON(http.StatusUnprocessableEntity, gin.H{
+			"error":    "runtime could not be resolved from the requested template; refusing to silently provision langgraph (controlplane#188). Pass an explicit \"runtime\", or use a template whose config.yaml declares one.",
+			"template": payload.Template,
+			"code":     "RUNTIME_UNRESOLVED",
+		})
+		return
+	}
 	if payload.Runtime == "" {
+		// Legitimate default path: no template AND no runtime requested
+		// (bare {"name":...}) — langgraph is the intended default here.
 		payload.Runtime = "langgraph"
 	}
 
@@ -512,7 +546,7 @@ func (h *WorkspaceHandler) Create(c *gin.Context) {
 			// shape. Adding a new snippet means adding it once there;
 			// all three callers pick it up automatically.
 			resp["connection"] = BuildExternalConnectionPayload(
-				externalPlatformURL(c), id, connectionToken,
+				externalPlatformURL(c), id, payload.Name, connectionToken,
 			)
 		}
 		c.JSON(http.StatusCreated, resp)

workspace-server/internal/handlers/workspace_test.go

@@ -718,7 +718,7 @@ func TestWorkspaceList_Empty(t *testing.T) {
 			"parent_id", "active_tasks", "last_error_rate", "last_sample_error",
 			"uptime_seconds", "current_task", "runtime", "workspace_dir", "x", "y", "collapsed",
 			"budget_limit", "monthly_spend",
-		"broadcast_enabled", "talk_to_user_enabled",
+			"broadcast_enabled", "talk_to_user_enabled",
 		}))
 
 	w := httptest.NewRecorder()
@@ -1770,3 +1770,147 @@ runtime_config:
 		t.Fatalf("expected 201, got %d: %s", w.Code, w.Body.String())
 	}
 }
+
+// ==================== #188 fail-closed: template/runtime contract ====================
+//
+// molecule-controlplane#188 / #184: if a caller names a `template` (intent
+// for a specific runtime) but the runtime cannot be resolved from it, the
+// server MUST NOT silently provision langgraph and return 201 — that false
+// success produced 5/5 wrong workspaces and a bogus codex E2E pass. These
+// tests pin the fail-closed boundary at the ws-server `Create` handler (the
+// path the product UI hits), and guard the legitimate default path against
+// regression.
+
+// Template requested but its dir/config.yaml is absent → 422, not silent
+// langgraph 201.
+func TestWorkspaceCreate_188_TemplateMissingRuntime_FailsClosed(t *testing.T) {
+	setupTestDB(t)
+	setupTestRedis(t)
+	broadcaster := newTestBroadcaster()
+	// configsDir is an empty temp dir → resolveInsideRoot succeeds (the path
+	// is inside root) but config.yaml read fails → runtime cannot be resolved.
+	configsDir := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(configsDir, "ghost-template"), 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", configsDir)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	body := `{"name":"Ghost","template":"ghost-template"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Create(c)
+
+	if w.Code != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 (fail-closed, controlplane#188), 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("parse: %v", err)
+	}
+	if resp["code"] != "RUNTIME_UNRESOLVED" {
+		t.Errorf("expected code RUNTIME_UNRESOLVED, got %v", resp["code"])
+	}
+}
+
+// Template config.yaml has no `runtime:` key → 422, not silent langgraph.
+func TestWorkspaceCreate_188_TemplateConfigNoRuntimeKey_FailsClosed(t *testing.T) {
+	setupTestDB(t)
+	setupTestRedis(t)
+	broadcaster := newTestBroadcaster()
+	configsDir := t.TempDir()
+	tdir := filepath.Join(configsDir, "noruntime-template")
+	if err := os.MkdirAll(tdir, 0o755); err != nil {
+		t.Fatalf("mkdir: %v", err)
+	}
+	// config.yaml exists but declares no runtime.
+	if err := os.WriteFile(filepath.Join(tdir, "config.yaml"), []byte("name: noruntime\n"), 0o644); err != nil {
+		t.Fatalf("write: %v", err)
+	}
+	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", configsDir)
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	body := `{"name":"NoRuntime","template":"noruntime-template"}`
+	c.Request = httptest.NewRequest("POST", "/workspaces", bytes.NewBufferString(body))
+	c.Request.Header.Set("Content-Type", "application/json")
+
+	handler.Create(c)
+
+	if w.Code != http.StatusUnprocessableEntity {
+		t.Fatalf("expected 422 (fail-closed), got %d: %s", w.Code, w.Body.String())
+	}
+}
+
+// Regression guard: the legitimate default path (no template, no runtime —
+// bare {"name":...}) MUST still default to langgraph and return 201. The
+// #188 fix must not break this.
+func TestWorkspaceCreate_188_NoTemplateNoRuntime_StillDefaultsLanggraph(t *testing.T) {
+	mock := setupTestDB(t)
+	setupTestRedis(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", t.TempDir())
+
+	mock.ExpectBegin()
+	mock.ExpectExec("INSERT INTO workspaces").
+		WithArgs(sqlmock.AnyArg(), "Plain Default", nil, 3, "langgraph", 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))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	body := `{"name":"Plain Default"}`
+	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.Fatalf("expected 201 (legitimate default path), got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet sqlmock expectations: %v", err)
+	}
+}
+
+// Explicit runtime, no template → honored, 201 (no template resolution
+// needed; runtimeExplicitlyRequested true but already resolved).
+func TestWorkspaceCreate_188_ExplicitRuntimeNoTemplate_OK(t *testing.T) {
+	mock := setupTestDB(t)
+	setupTestRedis(t)
+	broadcaster := newTestBroadcaster()
+	handler := NewWorkspaceHandler(broadcaster, nil, "http://localhost:8080", t.TempDir())
+
+	mock.ExpectBegin()
+	mock.ExpectExec("INSERT INTO workspaces").
+		WithArgs(sqlmock.AnyArg(), "Explicit Codex", nil, 3, "codex", 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))
+
+	w := httptest.NewRecorder()
+	c, _ := gin.CreateTestContext(w)
+	body := `{"name":"Explicit Codex","runtime":"codex"}`
+	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.Fatalf("expected 201, got %d: %s", w.Code, w.Body.String())
+	}
+	if err := mock.ExpectationsWereMet(); err != nil {
+		t.Errorf("unmet sqlmock expectations: %v", err)
+	}
+}

workspace-server/internal/provisioner/t4_privilege_contract.go

@@ -0,0 +1,229 @@
+// Package provisioner — T4 privilege contract.
+//
+// This file is the single source of truth for what a Tier-4 ("full
+// machine access") workspace runtime MUST guarantee, expressed as code
+// templates can reference and CI can verify.
+//
+// RFC: molecule-ai/internal#456 (per-template privilege-contract class).
+// Task: molecule-ai/internal #174.
+//
+// Background
+// ----------
+// Prior art is RFC#456's three layers:
+//
+//	(1) molecule-runtime self-enforces uid-1000 + fchown safety net,
+//	(2) a platform-owned wrapper entrypoint from a shared base image,
+//	(3) a REQUIRED CI conformance gate wired into the fresh-provision
+//	    harness that asserts the post-condition, not the mechanism.
+//
+// This file is the *data shape* for layer (3): the gate's tests have
+// been hand-written per-template (template-claude-code, template-hermes,
+// template-codex). Hand-writing drifts; the Hermes 401 class came from
+// drift. We need the capability list itself to be code so that:
+//
+//   - The provisioner can dump it as `t4_capabilities.yaml` for any
+//     fork user or non-Molecule-AI template runner to consume directly
+//     (no hardcoded internal org).
+//   - A `Verify(...)` helper turns into the t4-conformance shell out of
+//     one file, so when a capability is added the templates pick it up
+//     by reading the YAML — they do not silently lag.
+//   - The provisioner-emit side (provisioner.go applyTierResources / T4
+//     branch) and the verifier side share the same constants for the
+//     uid + mount paths, eliminating "string-match" drift between
+//     emitter and gate.
+//
+// Non-goals
+// ---------
+//   - This is NOT a substitute for layer (1)/(2). Templates still must
+//     `exec gosu agent` and write /configs/.auth_token under uid 1000;
+//     this file describes *what to check*, not how to achieve it.
+//   - This file does not run tests. It is the spec. CI workflows call
+//     `T4PrivilegeContract().AsYAML()` once at the start of the gate
+//     and assert each capability's `Probe` returns ok.
+package provisioner
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// T4Capability is one assertion the T4 runtime MUST satisfy.
+//
+// Each capability declares:
+//   - Name:        stable id (used as the test name in CI output).
+//   - Description: human-readable why-this-matters; goes in failure logs.
+//   - Probe:       a shell snippet that exits 0 on pass, non-zero on fail.
+//     The probe MUST be deterministic, MUST be runnable inside the
+//     running container under uid 1000, and MUST NOT depend on outside
+//     network beyond what `RequiredEgress` declares.
+//   - Severity:    "hard" capabilities fail the gate; "advisory" emit a
+//     warning. T4 contract minimum = all hard pass.
+//   - Source:      RFC section or memory reference that motivated this
+//     capability — keeps the audit trail in-tree.
+type T4Capability struct {
+	Name           string   `yaml:"name"`
+	Description    string   `yaml:"description"`
+	Probe          string   `yaml:"probe"`
+	Severity       string   `yaml:"severity"`
+	Source         string   `yaml:"source"`
+	RequiredEgress []string `yaml:"required_egress,omitempty"`
+}
+
+// SeverityHard / SeverityAdvisory enumerate the only allowed Severity
+// values. We do not use Go enums because the YAML consumer is shell.
+const (
+	SeverityHard     = "hard"
+	SeverityAdvisory = "advisory"
+)
+
+// T4PrivilegeContract returns the full T4 capability set.
+//
+// Add new capabilities here. Each one is automatically picked up by
+// any template whose CI consumes `t4_capabilities.yaml` (no per-template
+// PR needed for new checks — this is the anti-drift property).
+//
+// Capability ordering matters for human-readable CI output but is not
+// load-bearing for correctness; AsYAML() emits them sorted by Name.
+func T4PrivilegeContract() []T4Capability {
+	return []T4Capability{
+		{
+			Name:        "agent_uid_1000",
+			Description: "The container's primary process (the runtime, post-gosu) runs as uid 1000, not root. T4 grants full machine access via privileged + host PID + Docker socket — the WORKLOAD inside that privileged container must still be unprivileged to prevent every untrusted code execution from being trivially root-on-host.",
+			Probe:       `[ "$(id -u)" = "1000" ]`,
+			Severity:    SeverityHard,
+			Source:      "RFC internal#456 §2.1.2; memory feedback_hermes_listpeers_401_token_root600_unreadable_by_uid1000",
+		},
+		{
+			Name:        "auth_token_agent_owned",
+			Description: "/configs/.auth_token is owned by uid 1000 (== AgentUID) so the a2a_mcp_server can read its bearer. In SaaS mode molecule-runtime itself writes the token via save_token() — the ownership equals the runtime's exec uid. If the runtime ever runs as root, this fails and list_peers 401s (the Hermes class bug).",
+			Probe:       `[ -e /configs/.auth_token ] && [ "$(stat -c '%u' /configs/.auth_token)" = "1000" ]`,
+			Severity:    SeverityHard,
+			Source:      "RFC internal#456 §10; memory feedback_hermes_listpeers_401_token_root600_unreadable_by_uid1000",
+		},
+		{
+			Name:        "host_root_reach_via_nsenter",
+			Description: "The uid-1000 agent can attain host root via `sudo -n nsenter --target 1 --mount --pid -- id -u` returning 0. This is the T4 escalation leg: full machine access means the agent CAN escalate to host root deliberately, even though it does not run as root by default.",
+			Probe:       `[ "$(sudo -n nsenter --target 1 --mount --pid -- id -u)" = "0" ]`,
+			Severity:    SeverityHard,
+			Source:      "RFC internal#456 §11; memory reference_per_template_privilege_contract_class_audit_2026_05_16",
+		},
+		{
+			Name:        "host_fs_write_readback",
+			Description: "Host filesystem is mounted at /host and the agent can write+read+remove a file there via sudo. Proves real host reach (not just a PID-1 namespace trick on an isolated init).",
+			Probe: `MARKER="t4cap-$(date +%s)-$RANDOM"; PROBE_FILE="/host/tmp/.t4-cap-probe-${MOLECULE_T4_PROBE_ID:-$$}"; ` +
+				`sudo -n sh -c "echo $MARKER > $PROBE_FILE" && ` +
+				`[ "$(sudo -n cat $PROBE_FILE)" = "$MARKER" ] && ` +
+				`sudo -n rm -f $PROBE_FILE`,
+			Severity: SeverityHard,
+			Source:   "RFC internal#456 §11",
+		},
+		{
+			Name:        "docker_socket_reachable",
+			Description: "/var/run/docker.sock is bind-mounted into the container so the agent can manage other containers (T4 use case: agent-as-orchestrator). Proven by 'docker version' returning a server section, which requires the daemon to answer over the socket.",
+			Probe:       `sudo -n docker version --format '{{.Server.Version}}' >/dev/null 2>&1`,
+			Severity:    SeverityHard,
+			Source:      "provisioner.go applyHostConfig T4 branch (case 4)",
+		},
+		{
+			Name:        "list_peers_http_200",
+			Description: "The platform list_peers HTTP endpoint (served by the in-container a2a_mcp_server) returns HTTP 200 when called from uid 1000 with the bearer from /configs/.auth_token. This proves the WHOLE token-ownership chain end-to-end: token written under correct uid → reader uid matches → bearer non-empty → platform accepts. A self-contained empirical test for the Hermes class bug.",
+			Probe: `BEARER=$(cat /configs/.auth_token 2>/dev/null || echo ""); ` +
+				`[ -n "$BEARER" ] || exit 1; ` +
+				`PORT=$(cat /configs/.platform_port 2>/dev/null || echo "8080"); ` +
+				`STATUS=$(curl -sS -o /dev/null -w '%{http_code}' -H "Authorization: Bearer $BEARER" "http://127.0.0.1:${PORT}/list_peers"); ` +
+				`[ "$STATUS" = "200" ]`,
+			Severity: SeverityHard,
+			Source:   "memory reference_openclaw_fresh_provision_nonfunctional_anthropic_default_unroutable; memory reference_openclaw_mcp_peer_wiring_rootcause",
+		},
+		{
+			Name:        "agent_home_writable",
+			Description: "/agent-home is writable by the agent (Files API split per task #128). The Files API redesign uses /agent-home as the user-writable root; the agent must be able to create files there without sudo.",
+			Probe:       `TF=/agent-home/.t4-cap-write-probe-${MOLECULE_T4_PROBE_ID:-$$}; echo ok > "$TF" && [ "$(cat "$TF")" = "ok" ] && rm -f "$TF"`,
+			Severity:    SeverityHard,
+			Source:      "task #128 Files API redesign; memory reference_post_suspension_pipeline",
+		},
+		{
+			Name:        "network_egress_https",
+			Description: "Generic HTTPS egress works. T4 is unconstrained network; the canonical test target is the Gitea instance over its public name, which any fork user can also resolve. Any reachable HTTPS endpoint satisfies it — the YAML carries the recommended targets but accepts any 200/301/302.",
+			Probe: `for U in $MOLECULE_T4_EGRESS_TARGETS; do ` +
+				`  C=$(curl -sS -o /dev/null -w '%{http_code}' --max-time 8 "$U"); ` +
+				`  case "$C" in 2*|3*) exit 0;; esac; ` +
+				`done; exit 1`,
+			Severity: SeverityHard,
+			Source:   "task #174 brief",
+			RequiredEgress: []string{
+				// Public, no auth, returns a small JSON.
+				// Adopters override via MOLECULE_T4_EGRESS_TARGETS.
+				"https://api.github.com/zen",
+				"https://www.google.com/generate_204",
+			},
+		},
+		{
+			Name:        "privileged_flag_observable",
+			Description: "Container is started with --privileged. Observable from inside via /proc/self/status CapEff containing CAP_SYS_ADMIN. Defense-in-depth for the provisioner emission side.",
+			Probe:       `grep -q '^CapEff:.*ffffffffff' /proc/self/status`,
+			Severity:    SeverityAdvisory, // Imperfect — some CAP filters trim CapEff; advisory only.
+			Source:      "provisioner.go applyHostConfig T4 branch (case 4)",
+		},
+		{
+			Name:        "pid_host_visible",
+			Description: "Host PID namespace is shared (--pid=host). The container can see host process 1 (systemd or pid-1 on the EC2 instance). Required for nsenter into host mount/pid namespaces.",
+			Probe:       `[ -d /proc/1/root ] && [ "$(sudo -n readlink /proc/1/ns/pid)" = "$(sudo -n readlink /proc/self/ns/pid)" ]`,
+			Severity:    SeverityHard,
+			Source:      "provisioner.go applyHostConfig T4 branch (case 4): hostCfg.PidMode = 'host'",
+		},
+	}
+}
+
+// AsYAML renders the contract as a single YAML document templates can
+// fetch at CI time. Sorted by Name for deterministic diffs.
+//
+// We deliberately do not depend on a YAML library here — the format is
+// trivial, and one-file pure-stdlib means this can be vendored or
+// dumped from any Go context (including a `go run` script in CI).
+//
+// The format is stable; downstream consumers must treat unknown fields
+// as warnings, not errors.
+func AsYAML(caps []T4Capability) string {
+	sorted := make([]T4Capability, len(caps))
+	copy(sorted, caps)
+	sort.Slice(sorted, func(i, j int) bool { return sorted[i].Name < sorted[j].Name })
+
+	var b strings.Builder
+	b.WriteString("# T4 privilege contract — generated from\n")
+	b.WriteString("# molecule-ai/molecule-core workspace-server/internal/provisioner/t4_privilege_contract.go\n")
+	b.WriteString("# RFC: molecule-ai/internal#456\n")
+	b.WriteString("# Do NOT edit this file by hand; regenerate via `go run ./cmd/t4-contract-dump > t4_capabilities.yaml`.\n")
+	b.WriteString("version: 1\n")
+	b.WriteString("agent_uid: 1000\n")
+	b.WriteString("capabilities:\n")
+	for _, c := range sorted {
+		fmt.Fprintf(&b, "  - name: %s\n", yamlEscape(c.Name))
+		fmt.Fprintf(&b, "    description: %s\n", yamlEscape(c.Description))
+		fmt.Fprintf(&b, "    severity: %s\n", c.Severity)
+		fmt.Fprintf(&b, "    source: %s\n", yamlEscape(c.Source))
+		fmt.Fprintf(&b, "    probe: %s\n", yamlEscape(c.Probe))
+		if len(c.RequiredEgress) > 0 {
+			b.WriteString("    required_egress:\n")
+			for _, u := range c.RequiredEgress {
+				fmt.Fprintf(&b, "      - %s\n", yamlEscape(u))
+			}
+		}
+	}
+	return b.String()
+}
+
+// yamlEscape is a minimal YAML scalar escaper. We always quote with
+// double quotes and backslash-escape internal quotes + backslashes —
+// safe for the subset of strings we emit (no control chars except \n
+// and \t, both of which we replace with literal escapes).
+func yamlEscape(s string) string {
+	r := strings.NewReplacer(
+		"\\", "\\\\",
+		"\"", "\\\"",
+		"\n", "\\n",
+		"\t", "\\t",
+	)
+	return "\"" + r.Replace(s) + "\""
+}

workspace-server/internal/provisioner/t4_privilege_contract_test.go

@@ -0,0 +1,153 @@
+package provisioner
+
+import (
+	"strings"
+	"testing"
+)
+
+// TestT4PrivilegeContract_AllCapabilitiesHaveRequiredFields enforces
+// the invariant that every entry in the contract has at minimum a
+// Name, Description, Probe, Severity, and Source — so the YAML the
+// templates consume is never partially-filled (a quiet way to drift).
+func TestT4PrivilegeContract_AllCapabilitiesHaveRequiredFields(t *testing.T) {
+	caps := T4PrivilegeContract()
+	if len(caps) == 0 {
+		t.Fatal("T4PrivilegeContract returned zero capabilities — the gate would have nothing to assert")
+	}
+	for _, c := range caps {
+		if c.Name == "" {
+			t.Errorf("capability missing Name: %+v", c)
+		}
+		if c.Description == "" {
+			t.Errorf("capability %q missing Description", c.Name)
+		}
+		if c.Probe == "" {
+			t.Errorf("capability %q missing Probe", c.Name)
+		}
+		if c.Severity != SeverityHard && c.Severity != SeverityAdvisory {
+			t.Errorf("capability %q has invalid Severity %q (allowed: hard, advisory)", c.Name, c.Severity)
+		}
+		if c.Source == "" {
+			t.Errorf("capability %q missing Source — every capability must cite the RFC section or memory that motivates it", c.Name)
+		}
+	}
+}
+
+// TestT4PrivilegeContract_NamesAreUnique catches a silent
+// dup-by-rename: if two capabilities share a name, AsYAML overwrites
+// one in any YAML-loader-with-merge implementation, and CI output
+// becomes ambiguous.
+func TestT4PrivilegeContract_NamesAreUnique(t *testing.T) {
+	caps := T4PrivilegeContract()
+	seen := make(map[string]bool, len(caps))
+	for _, c := range caps {
+		if seen[c.Name] {
+			t.Errorf("capability name %q appears more than once", c.Name)
+		}
+		seen[c.Name] = true
+	}
+}
+
+// TestT4PrivilegeContract_CoreCapabilitiesPresent pins the minimum
+// closure of capabilities the gate guarantees. Adding capabilities
+// is fine; removing one of these requires updating this test
+// (which the reviewer will see and challenge).
+//
+// These are exactly the post-conditions cited in RFC internal#456 §10–§11
+// + task #128 (Files API) + task #174 (this task).
+func TestT4PrivilegeContract_CoreCapabilitiesPresent(t *testing.T) {
+	required := []string{
+		"agent_uid_1000",
+		"auth_token_agent_owned",
+		"host_root_reach_via_nsenter",
+		"docker_socket_reachable",
+		"list_peers_http_200",
+		"agent_home_writable",
+		"network_egress_https",
+	}
+	caps := T4PrivilegeContract()
+	have := make(map[string]bool, len(caps))
+	for _, c := range caps {
+		have[c.Name] = true
+	}
+	for _, r := range required {
+		if !have[r] {
+			t.Errorf("required capability %q missing from contract — RFC internal#456 / task #174 says this MUST be in the closure", r)
+		}
+	}
+}
+
+// TestT4PrivilegeContract_HardCapabilitiesMajority sanity-checks that
+// the contract is not silently advisory-only. If someone marks
+// everything as "advisory" the gate becomes a no-op without anyone
+// noticing — fail the test if hard capabilities are not the majority.
+func TestT4PrivilegeContract_HardCapabilitiesMajority(t *testing.T) {
+	caps := T4PrivilegeContract()
+	hard := 0
+	for _, c := range caps {
+		if c.Severity == SeverityHard {
+			hard++
+		}
+	}
+	if hard*2 <= len(caps) {
+		t.Errorf("hard capabilities (%d) must be the strict majority of %d total — otherwise the gate is a no-op", hard, len(caps))
+	}
+}
+
+// TestAsYAML_IsParseableAndStable asserts the AsYAML output is
+// stable across invocations (sorted by name) and contains every
+// capability's name. We do not depend on a YAML parser here —
+// presence of `- name: "<n>"` lines is sufficient and the format
+// is deliberately the trivially-greppable subset.
+func TestAsYAML_IsParseableAndStable(t *testing.T) {
+	caps := T4PrivilegeContract()
+	y1 := AsYAML(caps)
+	y2 := AsYAML(caps)
+	if y1 != y2 {
+		t.Error("AsYAML output is not deterministic across calls — sort/format must be stable for CI diff sanity")
+	}
+	for _, c := range caps {
+		needle := "- name: \"" + c.Name + "\""
+		if !strings.Contains(y1, needle) {
+			t.Errorf("AsYAML output missing %q", needle)
+		}
+	}
+	// Header must cite the RFC so adopters can find the source of truth.
+	if !strings.Contains(y1, "internal#456") {
+		t.Error("AsYAML header must reference RFC internal#456 — that is the design-of-record")
+	}
+	if !strings.Contains(y1, "version: 1") {
+		t.Error("AsYAML must declare schema version (templates parse-check on this)")
+	}
+}
+
+// TestAsYAML_EscapesEmbeddedQuotes catches a regression in
+// yamlEscape: a probe shell string containing a double-quote would
+// produce an unparseable YAML scalar.
+func TestAsYAML_EscapesEmbeddedQuotes(t *testing.T) {
+	caps := []T4Capability{{
+		Name:        "embedded_quote",
+		Description: `says "hi"`,
+		Probe:       `echo "ok"`,
+		Severity:    SeverityHard,
+		Source:      "test",
+	}}
+	y := AsYAML(caps)
+	// We expect the embedded `"` to be backslash-escaped.
+	if !strings.Contains(y, `\"hi\"`) {
+		t.Errorf("AsYAML did not escape embedded double quotes; got:\n%s", y)
+	}
+	if !strings.Contains(y, `\"ok\"`) {
+		t.Errorf("AsYAML did not escape embedded double quotes in Probe; got:\n%s", y)
+	}
+}
+
+// TestAgentUIDConsistency ties the contract to the existing
+// provisioner-side AgentUID const. The probe for "agent_uid_1000"
+// hard-codes `id -u == 1000`; if AgentUID ever changes (no one
+// expects it to, but a CI guard is free), the probe must change too.
+func TestAgentUIDConsistency(t *testing.T) {
+	if AgentUID != 1000 {
+		t.Fatalf("AgentUID is %d but the T4 contract's probes assume 1000; update t4_privilege_contract.go probes before changing AgentUID", AgentUID)
+	}
+}

workspace-server/internal/secrets/patterns_test.go

@@ -81,11 +81,11 @@ func TestPositiveMatches(t *testing.T) {
 		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"},
+		{"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"},
@@ -156,7 +156,7 @@ func TestNegativeShapes(t *testing.T) {
 // makes ScanString do its own thing (e.g. accidentally normalise
 // case) would diverge silently.
 func TestScanString_NoOp(t *testing.T) {
-	in := "ghp_EXAMPLE111122223333444455556666777788889999"
+	in := "ghp_" + "EXAMPLE111122223333444455556666777788889999"
 	m1, err1 := ScanBytes([]byte(in))
 	if err1 != nil {
 		t.Fatalf("ScanBytes errored: %v", err1)

workspace/Dockerfile

@@ -62,6 +62,19 @@ RUN chmod +x ./scripts/molecule-git-token-helper.sh
 COPY scripts/molecule-gh-token-refresh.sh ./scripts/
 RUN chmod +x ./scripts/molecule-gh-token-refresh.sh
 
+# Generic GIT_ASKPASS helper. Reads HTTPS Basic-Auth credentials from env
+# vars (GIT_HTTP_USERNAME / GIT_HTTP_PASSWORD, with GITEA_USER / GITEA_TOKEN
+# as fallback) and emits them on the git credential-prompt protocol so
+# container-side `git` can authenticate to any private HTTPS remote
+# without on-disk .gitconfig / .git-credentials mutation. The platform
+# provisioner sets GIT_ASKPASS=/usr/local/bin/molecule-askpass via
+# applyAgentGitIdentity (workspace-server/internal/handlers/agent_git_identity.go).
+# Filename is the only project-specific marker; the script body contains
+# no vendor literals and is identical to the script shipped in each
+# open-source workspace template (scripts/git-askpass.sh).
+COPY scripts/molecule-askpass /usr/local/bin/molecule-askpass
+RUN chmod +x /usr/local/bin/molecule-askpass
+
 # Dirs and permissions
 RUN mkdir -p /workspace /plugins /home/agent/.claude /home/agent/.config /home/agent/.local \
     /home/agent/.molecule-token-cache && \

workspace/a2a_mcp_server.py

@@ -172,6 +172,12 @@ async def handle_tool_call(name: str, arguments: dict) -> str:
             arguments.get("message", ""),
             workspace_id=arguments.get("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"),
+        )
     return f"Unknown tool: {name}"
 
 

workspace/scripts/molecule-askpass

@@ -0,0 +1,35 @@
+#!/bin/sh
+# git-askpass helper. Reads HTTPS Basic-Auth credentials from env vars so
+# the deployer can wire git authentication for any private remote without
+# touching ~/.gitconfig or ~/.git-credentials inside the container.
+#
+# Wire-up: set GIT_ASKPASS=/usr/local/bin/molecule-askpass in the
+# container env, then export GIT_HTTP_USERNAME / GIT_HTTP_PASSWORD (or the
+# GITEA_USER / GITEA_TOKEN fallback pair). When git encounters an HTTPS
+# auth challenge on a host that has no credential.helper configured for
+# it, git invokes GIT_ASKPASS twice — once with a "Username for ..."
+# prompt and once with a "Password for ..." prompt. We pattern-match on
+# that prompt and emit the matching env var.
+#
+# No hardcoded hostnames or vendor names — the deployer decides which
+# host these credentials apply to by virtue of setting GIT_ASKPASS only
+# when the target remote is in scope. The helper itself is reusable for
+# any HTTPS git remote.
+#
+# Failure mode: if the env vars are unset, we emit an empty string and
+# let git surface "Authentication failed" — this is intentional, so a
+# misconfigured deployment fails loudly at first push instead of silently
+# falling through to an unrelated credential chain.
+
+case "$1" in
+    Username*)
+        printf '%s\n' "${GIT_HTTP_USERNAME:-${GITEA_USER:-}}"
+        ;;
+    Password*)
+        printf '%s\n' "${GIT_HTTP_PASSWORD:-${GITEA_TOKEN:-}}"
+        ;;
+    *)
+        # Unknown prompt — emit empty and let git decide.
+        printf '\n'
+        ;;
+esac