Merge pull request #2942 from Molecule-AI/staging

staging → main: auto-promote 1ad107c
Merge pull request #2938 from Molecule-AI/staging
2026-05-05 14:47:21 -07:00 · 2026-05-05 21:29:56 +00:00 · 2026-05-05 21:25:57 +00:00 · 2026-05-05 14:22:57 -07:00 · 2026-05-05 14:19:09 -07:00 · 2026-05-05 21:07:44 +00:00
281 changed files with 40709 additions and 3349 deletions
@@ -186,7 +186,7 @@ jobs:
              echo "proceed=true" >> "$GITHUB_OUTPUT"
              echo "::notice::E2E green for this SHA — proceeding with promote"
              ;;
-            completed/failure|completed/cancelled|completed/timed_out)
+            completed/failure|completed/timed_out)
              echo "proceed=false" >> "$GITHUB_OUTPUT"
              {
                echo "## ❌ Auto-promote aborted — E2E Staging SaaS failed"
@@ -198,6 +198,27 @@ jobs:
              } >> "$GITHUB_STEP_SUMMARY"
              exit 1
              ;;
+            completed/cancelled)
+              # cancelled ≠ failure. Per-SHA concurrency cancels older E2E
+              # runs when a newer push lands (memory:
+              # feedback_concurrency_group_per_sha) — the newer SHA will
+              # have its own E2E + promote chain. Treat the same as
+              # in_progress: defer without aborting, let the next E2E run
+              # promote when it lands.
+              #
+              # Caught 2026-05-05 02:03 on sha 31f9a5e — auto-promote
+              # blocked the whole chain because this case fell through to
+              # exit 1 instead of clean defer.
+              echo "proceed=false" >> "$GITHUB_OUTPUT"
+              {
+                echo "## ⏭ Auto-promote deferred — E2E Staging SaaS was cancelled"
+                echo
+                echo "E2E Staging SaaS for \`${SHA:0:7}\`: \`$RESULT\`"
+                echo "Likely per-SHA concurrency (newer push superseded this E2E run)."
+                echo "The newer SHA's E2E will fire its own promote when it lands."
+                echo "If you need this specific SHA promoted, manually dispatch."
+              } >> "$GITHUB_STEP_SUMMARY"
+              ;;
            in_progress/*|queued/*|requested/*|waiting/*|pending/*)
              echo "proceed=false" >> "$GITHUB_OUTPUT"
              {
@@ -0,0 +1,81 @@
+name: branch-protection drift check
+
+# Catches out-of-band edits to branch protection (UI clicks, manual gh
+# api PATCH from a one-off ops session) by comparing live state against
+# tools/branch-protection/apply.sh's desired state every day. Fails the
+# workflow when they drift; the failure is the signal.
+#
+# When it fails: re-run apply.sh to put the live state back to the
+# script's intent, OR update apply.sh to encode the new intent and
+# commit. Either way the script is the source of truth.
+
+on:
+  schedule:
+    # 14:00 UTC daily. Off-hours for most teams; gives a fresh signal
+    # at the start of every working day.
+    - cron: '0 14 * * *'
+  workflow_dispatch:
+  pull_request:
+    branches: [staging, main]
+    paths:
+      - 'tools/branch-protection/**'
+      - '.github/workflows/branch-protection-drift.yml'
+
+permissions:
+  contents: read
+
+jobs:
+  drift:
+    name: Branch protection drift
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # Token strategy by trigger:
+      #
+      # - schedule (daily canary): hard-fail when the admin token is
+      #   missing. This is the *only* trigger where silent soft-skip is
+      #   dangerous — a missing secret on the cron run means the drift
+      #   gate has effectively disappeared with no human in the loop to
+      #   notice. Per feedback_schedule_vs_dispatch_secrets_hardening.md
+      #   the rule is "schedule/automated triggers must hard-fail".
+      #
+      # - pull_request (touching tools/branch-protection/**): soft-skip
+      #   with a prominent warning. A PR cannot retroactively drift the
+      #   live state — drift happens *between* PRs (UI clicks, manual
+      #   gh api PATCH) and is the schedule's job to catch. The PR-time
+      #   gate would only catch typos in apply.sh, which the apply.sh
+      #   *_payload unit tests catch better. A human is reviewing the
+      #   PR and will see the warning in the workflow log.
+      #
+      # - workflow_dispatch (operator one-off): soft-skip with warning,
+      #   so an operator can run a diagnostic without configuring the
+      #   secret first.
+      - name: Verify admin token present (hard-fail on schedule only)
+        env:
+          GH_TOKEN_FOR_ADMIN_API: ${{ secrets.GH_TOKEN_FOR_ADMIN_API }}
+        run: |
+          if [[ -n "$GH_TOKEN_FOR_ADMIN_API" ]]; then
+            echo "GH_TOKEN_FOR_ADMIN_API present — drift_check will run with admin scope."
+            exit 0
+          fi
+          if [[ "${{ github.event_name }}" == "schedule" ]]; then
+            echo "::error::GH_TOKEN_FOR_ADMIN_API secret missing on the daily canary." >&2
+            echo "" >&2
+            echo "The schedule run is the SoT for branch-protection drift detection." >&2
+            echo "Without admin scope it silently passes, hiding any out-of-band edits." >&2
+            echo "Set GH_TOKEN_FOR_ADMIN_API at Settings → Secrets and variables → Actions." >&2
+            exit 1
+          fi
+          echo "::warning::GH_TOKEN_FOR_ADMIN_API secret missing — drift_check will be SKIPPED."
+          echo "::warning::PR drift checks need repo-admin scope to read /branches/:b/protection."
+          echo "::warning::This is non-fatal: the daily schedule run is the canonical drift gate."
+          echo "SKIP_DRIFT_CHECK=1" >> "$GITHUB_ENV"
+
+      - name: Run drift check
+        if: env.SKIP_DRIFT_CHECK != '1'
+        env:
+          # Repo-admin scope, needed for /branches/:b/protection.
+          GH_TOKEN: ${{ secrets.GH_TOKEN_FOR_ADMIN_API }}
+        run: bash tools/branch-protection/drift_check.sh
@@ -50,19 +50,35 @@ jobs:
    env:
      MOLECULE_CP_URL: https://staging-api.moleculesai.app
      MOLECULE_ADMIN_TOKEN: ${{ secrets.MOLECULE_STAGING_ADMIN_TOKEN }}
-      # Without an LLM key the test_staging_full_saas.sh script provisions
-      # the workspace with empty secrets, hermes derive-provider.sh resolves
-      # `openai/gpt-4o` to PROVIDER=openrouter, no OPENROUTER_API_KEY is
-      # found in env, and A2A returns "No LLM provider configured" at
-      # request time (canary step 8/11). The full-lifecycle workflow
-      # (e2e-staging-saas.yml) has carried this secret since launch — the
-      # canary regressed when it was first split out and lost the env
-      # block. Issue #1500 had ~30 consecutive failures before this was
-      # spotted; do NOT remove without re-reading the script's secrets-
-      # injection block.
+      # MiniMax is the canary's PRIMARY LLM auth path post-2026-05-04.
+      # Switched from hermes+OpenAI after #2578 (the staging OpenAI key
+      # account went over quota and stayed dead for 36+ hours, taking
+      # the canary red the entire time). claude-code template's
+      # `minimax` provider routes ANTHROPIC_BASE_URL to
+      # api.minimax.io/anthropic and reads MINIMAX_API_KEY at boot —
+      # ~5-10x cheaper per token than gpt-4.1-mini AND on a separate
+      # billing account, so OpenAI quota collapse no longer wedges the
+      # canary. Mirrors the migration continuous-synth-e2e.yml made on
+      # 2026-05-03 (#265) for the same reason. tests/e2e/test_staging_
+      # full_saas.sh branches SECRETS_JSON on which key is present —
+      # MiniMax wins when set.
+      E2E_MINIMAX_API_KEY: ${{ secrets.MOLECULE_STAGING_MINIMAX_API_KEY }}
+      # Direct-Anthropic alternative for operators who don't want to
+      # set up a MiniMax account (priority below MiniMax — first
+      # non-empty wins in test_staging_full_saas.sh's secrets-injection
+      # block). See #2578 PR comment for the rationale.
+      E2E_ANTHROPIC_API_KEY: ${{ secrets.MOLECULE_STAGING_ANTHROPIC_API_KEY }}
+      # OpenAI fallback — kept wired so an operator-dispatched run with
+      # E2E_RUNTIME=hermes overridden via workflow_dispatch can still
+      # exercise the OpenAI path without re-editing the workflow.
      E2E_OPENAI_API_KEY: ${{ secrets.MOLECULE_STAGING_OPENAI_KEY }}
      E2E_MODE: canary
-      E2E_RUNTIME: hermes
+      E2E_RUNTIME: claude-code
+      # Pin the canary to a specific MiniMax model rather than relying
+      # on the per-runtime default (which could resolve to "sonnet" →
+      # direct Anthropic and defeat the cost saving). M2.7-highspeed
+      # is "Token Plan only" but cheap-per-token and fast.
+      E2E_MODEL_SLUG: MiniMax-M2.7-highspeed
      E2E_RUN_ID: "canary-${{ github.run_id }}"

    steps:
@@ -75,13 +91,47 @@ jobs:
            exit 2
          fi

-      - name: Verify OpenAI key present
+      - name: Verify LLM key present
        run: |
-          if [ -z "$E2E_OPENAI_API_KEY" ]; then
-            echo "::error::MOLECULE_STAGING_OPENAI_KEY secret not set — A2A will fail at request time with 'No LLM provider configured'"
+          # Per-runtime key check — claude-code uses MiniMax; hermes /
+          # langgraph (operator-dispatched only) use OpenAI. Hard-fail
+          # rather than soft-skip per the lesson from synth E2E #2578:
+          # an empty key silently falls through to the wrong
+          # SECRETS_JSON branch and the canary fails 5 min later with
+          # a confusing auth error instead of the clean "secret
+          # missing" message at the top.
+          case "${E2E_RUNTIME}" in
+            claude-code)
+              # Either MiniMax OR direct-Anthropic works — first
+              # non-empty wins in the test script's secrets-injection
+              # priority chain. Operators only need to set ONE of these
+              # secrets; we don't force a choice between them.
+              if [ -n "${E2E_MINIMAX_API_KEY:-}" ]; then
+                required_secret_name="MOLECULE_STAGING_MINIMAX_API_KEY"
+                required_secret_value="${E2E_MINIMAX_API_KEY}"
+              elif [ -n "${E2E_ANTHROPIC_API_KEY:-}" ]; then
+                required_secret_name="MOLECULE_STAGING_ANTHROPIC_API_KEY"
+                required_secret_value="${E2E_ANTHROPIC_API_KEY}"
+              else
+                required_secret_name="MOLECULE_STAGING_MINIMAX_API_KEY or MOLECULE_STAGING_ANTHROPIC_API_KEY"
+                required_secret_value=""
+              fi
+              ;;
+            langgraph|hermes)
+              required_secret_name="MOLECULE_STAGING_OPENAI_KEY"
+              required_secret_value="${E2E_OPENAI_API_KEY:-}"
+              ;;
+            *)
+              echo "::warning::Unknown E2E_RUNTIME='${E2E_RUNTIME}' — skipping LLM-key check"
+              required_secret_name=""
+              required_secret_value="present"
+              ;;
+          esac
+          if [ -n "$required_secret_name" ] && [ -z "$required_secret_value" ]; then
+            echo "::error::${required_secret_name} secret not set for runtime=${E2E_RUNTIME} — A2A will fail at request time with 'No LLM provider configured'"
            exit 2
          fi
-          echo "OpenAI key present ✓ (len=${#E2E_OPENAI_API_KEY})"
+          echo "LLM key present ✓ (runtime=${E2E_RUNTIME}, key=${required_secret_name}, len=${#required_secret_value})"

      - name: Canary run
        id: canary
@@ -231,10 +281,38 @@ jobs:
                        and o.get('status') not in ('purged',)]
          print('\n'.join(candidates))
          " 2>/dev/null)
+          # Per-slug DELETE with HTTP-code verification. The previous
+          # `... >/dev/null || true` swallowed every failure, so a 5xx
+          # or timeout from CP looked identical to "successfully cleaned
+          # up" and the tenant kept eating ~2 vCPU until the hourly
+          # stale sweep caught it (up to 2h later). Now we capture the
+          # response code and surface non-2xx as a workflow warning, so
+          # the run page shows which slug leaked. We still don't `exit 1`
+          # on cleanup failure — a single-canary cleanup miss shouldn't
+          # fail-flag the canary itself when the actual smoke check
+          # passed. The sweep-stale-e2e-orgs cron (now every 15 min,
+          # 30-min threshold) is the safety net for whatever slips past.
+          # See molecule-controlplane#420.
+          leaks=()
          for slug in $orgs; do
-            curl -sS -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
+            # Tempfile-routed -w + set +e/-e prevents curl-exit-code
+            # pollution of the captured status (lint-curl-status-capture.yml).
+            set +e
+            curl -sS -o /tmp/canary-cleanup.out -w "%{http_code}" \
+              -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
              -H "Authorization: Bearer $ADMIN_TOKEN" \
              -H "Content-Type: application/json" \
-              -d "{\"confirm\":\"$slug\"}" >/dev/null || true
+              -d "{\"confirm\":\"$slug\"}" >/tmp/canary-cleanup.code
+            set -e
+            code=$(cat /tmp/canary-cleanup.code 2>/dev/null || echo "000")
+            if [ "$code" = "200" ] || [ "$code" = "204" ]; then
+              echo "[teardown] deleted $slug (HTTP $code)"
+            else
+              echo "::warning::canary teardown for $slug returned HTTP $code — sweep-stale-e2e-orgs will catch it within ~45 min. Body: $(head -c 300 /tmp/canary-cleanup.out 2>/dev/null)"
+              leaks+=("$slug")
+            fi
          done
+          if [ ${#leaks[@]} -gt 0 ]; then
+            echo "::warning::canary teardown left ${#leaks[@]} leak(s): ${leaks[*]}"
+          fi
          exit 0
@@ -272,6 +272,26 @@ jobs:
          find tests/e2e infra/scripts -type f -name '*.sh' -print0 \
            | xargs -0 shellcheck --severity=warning

+      - if: needs.changes.outputs.scripts == 'true'
+        name: Lint cleanup-trap hygiene (RFC #2873)
+        # Asserts every shell E2E test that calls `mktemp` also installs
+        # an EXIT trap. Catches the /tmp-leak class — a missing trap
+        # silently leaks scratch into CI runners (~10-100KB per run).
+        # See tests/e2e/lint_cleanup_traps.sh for the rule + fix pattern.
+        run: bash tests/e2e/lint_cleanup_traps.sh
+
+      - if: needs.changes.outputs.scripts == 'true'
+        name: Run E2E bash unit tests (no live infra)
+        # Pure-bash unit tests for E2E helper libs (lib/*.sh). These pin
+        # behavior of dispatch logic that — when broken — silently masks as
+        # "Could not resolve authentication method" only after a successful
+        # tenant + workspace provision (PR #2571 incident, 2026-05-03). Add
+        # new self-contained unit tests here as the lib/ directory grows;
+        # tests requiring live CP/tenant credentials belong in the dedicated
+        # e2e-staging-* workflows, not this job.
+        run: |
+          bash tests/e2e/test_model_slug.sh
+
  canvas-deploy-reminder:
    name: Canvas Deploy Reminder
    runs-on: ubuntu-latest
@@ -346,6 +366,72 @@ jobs:
      - if: needs.changes.outputs.python == 'true'
        run: python -m pytest --tb=short

+      - if: needs.changes.outputs.python == 'true'
+        name: Per-file critical-path coverage (MCP / inbox / auth)
+        # MCP-critical Python files have a per-file floor on top of the
+        # 86% total floor in pytest.ini. Rationale (issue #2790, after
+        # the PR #2766 → PR #2771 cycle): the total floor averages ~6000
+        # lines, so a single MCP file could regress to ~50% with no
+        # complaint as long as other modules compensate. These five
+        # files handle multi-tenant routing + auth + inbox dispatch —
+        # a coverage drop here is the same risk shape as a Go-side
+        # workspace-server token/secrets file dropping below 10%.
+        #
+        # Floor 75% sits below current actuals (80-96%) so this gate is
+        # strictly additive — no existing PR fails. Ratchet plan in
+        # COVERAGE_FLOOR.md.
+        run: |
+          set -e
+          PER_FILE_FLOOR=75
+          CRITICAL_FILES=(
+            "a2a_mcp_server.py"
+            "mcp_cli.py"
+            "a2a_tools.py"
+            "inbox.py"
+            "platform_auth.py"
+          )
+
+          # pytest already wrote .coverage; emit a JSON view scoped to
+          # the critical files so jq/python can read the per-file pct
+          # without parsing tabular text. --include uses fnmatch, and
+          # the leading "*" allows the file to live anywhere under the
+          # workspace root (today they sit at workspace/<name>.py).
+          INCLUDES=$(printf '*%s,' "${CRITICAL_FILES[@]}")
+          INCLUDES="${INCLUDES%,}"
+          python -m coverage json -o /tmp/critical-cov.json --include="$INCLUDES"
+
+          FAILED=0
+          for f in "${CRITICAL_FILES[@]}"; do
+            # Match by top-level path key (e.g. "a2a_tools.py", not
+            # "builtin_tools/a2a_tools.py" — different file at 100%).
+            # The keys in coverage.json are paths relative to the run
+            # cwd (workspace/), so the critical-path entry sits at the
+            # bare basename.
+            pct=$(jq -r --arg f "$f" '.files | to_entries | map(select(.key == $f)) | .[0].value.summary.percent_covered // "MISSING"' /tmp/critical-cov.json)
+            if [ "$pct" = "MISSING" ]; then
+              echo "::error file=workspace/$f::No coverage data — file may have moved or test exclusion mis-set."
+              FAILED=$((FAILED+1))
+              continue
+            fi
+            echo "$f: ${pct}%"
+            if awk "BEGIN{exit !($pct < $PER_FILE_FLOOR)}"; then
+              echo "::error file=workspace/$f::${pct}% < ${PER_FILE_FLOOR}% per-file floor (MCP critical path). See COVERAGE_FLOOR.md."
+              FAILED=$((FAILED+1))
+            fi
+          done
+
+          if [ "$FAILED" -gt 0 ]; then
+            echo ""
+            echo "$FAILED MCP critical-path file(s) below the ${PER_FILE_FLOOR}% per-file floor."
+            echo "These paths handle multi-tenant routing, auth tokens, and inbox dispatch."
+            echo "A coverage drop here is the same risk shape as Go-side tokens/secrets files"
+            echo "dropping below 10% (see COVERAGE_FLOOR.md). Either:"
+            echo "  (a) add tests to raise coverage back above ${PER_FILE_FLOOR}%, or"
+            echo "  (b) if this is unavoidable historical debt, file an issue and propose"
+            echo "      adjusting the floor with rationale in COVERAGE_FLOOR.md."
+            exit 1
+          fi
+
      # SDK + plugin validation moved to standalone repo:
      # github.com/Molecule-AI/molecule-sdk-python

@@ -32,16 +32,41 @@ name: Continuous synthetic E2E (staging)

 on:
  schedule:
-    # Every 20 minutes, on the :00 :20 :40. Offsets the existing :15
-    # sweep-cf-orphans and :45 sweep-cf-tunnels so the three
-    # operations don't all hit Cloudflare/AWS at the same minute.
-    - cron: '0,20,40 * * * *'
+    # Every 10 minutes, on :02 :12 :22 :32 :42 :52. Three constraints:
+    #   1. Stay off the top-of-hour. GitHub Actions scheduler drops
+    #      :00 firings under high load (own docs:
+    #      https://docs.github.com/en/actions/using-workflows/events-that-trigger-workflows#schedule).
+    #      Prior history: cron was '0,20,40' (2026-05-02) — only :00
+    #      ever survived. Bumped to '10,30,50' (2026-05-03) on the
+    #      theory that further-from-:00 wins. Empirically 2026-05-04
+    #      that ALSO dropped to ~60 min effective cadence (only ~1
+    #      schedule fire per hour — see molecule-core#2726). Detection
+    #      latency was claimed 20 min, actual 60 min.
+    #   2. Avoid colliding with the existing :15 sweep-cf-orphans
+    #      and :45 sweep-cf-tunnels — both hit the CF API and we
+    #      don't want to fight for rate-limit tokens.
+    #   3. Avoid the :30 heavy slot (canary-staging /30, sweep-aws-
+    #      secrets, sweep-stale-e2e-orgs every :15) — multiple
+    #      overlapping cron registrations on the same minute is part
+    #      of what GH drops under load.
+    # Solution: bump fires-per-hour 3 → 6 AND keep all slots in clean
+    # lanes (1-3 min away from any other cron). Even with empirically-
+    # observed ~67% GH drop ratio, 6 attempts/hour yields ~2 effective
+    # fires = ~30 min cadence; closer to the 20-min target than the
+    # current shape and provides a real degradation alarm if drops
+    # get worse.
+    - cron: '2,12,22,32,42,52 * * * *'
  workflow_dispatch:
    inputs:
      runtime:
-        description: "Runtime to provision (langgraph = fastest, default; hermes = slower but covers SDK-native path; claude-code = needs OAUTH token in tenant env)"
+        description: "Runtime to provision (claude-code = default + cheapest via MiniMax; langgraph = OpenAI-only; hermes = SDK-native path, slower)"
        required: false
-        default: "langgraph"
+        default: "claude-code"
+        type: string
+      model_slug:
+        description: "Model id to provision the workspace with (default MiniMax-M2.7-highspeed; e.g. 'sonnet' to test direct Anthropic, 'openai/gpt-4o' for hermes)"
+        required: false
+        default: "MiniMax-M2.7-highspeed"
        type: string
      keep_org:
        description: "Skip teardown for post-mortem debugging (only manual dispatch — never set this for cron runs)"
@@ -68,15 +93,36 @@ jobs:
  synth:
    name: Synthetic E2E against staging
    runs-on: ubuntu-latest
-    timeout-minutes: 12
+    # Bumped from 12 → 20 (2026-05-04). Tenant user-data install phase
+    # (apt-get update + install docker.io/jq/awscli/caddy + snap install
+    # ssm-agent) runs from raw Ubuntu on every boot — none of it is
+    # pre-baked into the tenant AMI. Empirical fetch_secrets/ok timing
+    # across today's canaries: 51s → 82s → 143s → 625s. apt-mirror tail
+    # latency drives the boot-to-fetch_secrets phase from ~1min to >10min.
+    # A 12min budget leaves only ~2min for the workspace (which needs
+    # ~3.5min for claude-code cold boot) on slow-apt days, blowing the
+    # budget. 20min absorbs the worst tenant tail so the workspace probe
+    # gets the full ~7min it needs even on a slow apt day. Real fix:
+    # pre-bake caddy + ssm-agent into the tenant AMI (controlplane#TBD).
+    timeout-minutes: 20
    env:
-      # langgraph default keeps cold-start under 5 min on staging EC2.
-      # hermes is slower (~7-10 min) and isn't needed for the
-      # regression class this gate exists to catch (deployment-pipeline
-      # + schema-drift + integration). Operators can pick hermes via
-      # workflow_dispatch when they need to exercise the SDK-native
-      # session path.
-      E2E_RUNTIME: ${{ github.event.inputs.runtime || 'langgraph' }}
+      # claude-code default: cold-start ~5 min (comparable to langgraph),
+      # but uses MiniMax-M2.7-highspeed via the template's third-party-
+      # Anthropic-compat path (workspace-configs-templates/claude-code-
+      # default/config.yaml:64-69). MiniMax is ~5-10x cheaper than
+      # gpt-4.1-mini per token AND avoids the recurring OpenAI quota-
+      # exhaustion class that took the canary down 2026-05-03 (#265).
+      # Operators can pick langgraph / hermes via workflow_dispatch
+      # when they specifically need to exercise the OpenAI or SDK-
+      # native paths.
+      E2E_RUNTIME: ${{ github.event.inputs.runtime || 'claude-code' }}
+      # Pin the canary to a specific MiniMax model rather than relying
+      # on the per-runtime default ("sonnet" → routes to direct
+      # Anthropic, defeats the cost saving). Operators can override
+      # via workflow_dispatch by setting a different E2E_MODEL_SLUG
+      # input if they need to exercise a specific model. M2.7-highspeed
+      # is "Token Plan only" but cheap-per-token and fast.
+      E2E_MODEL_SLUG: ${{ github.event.inputs.model_slug || 'MiniMax-M2.7-highspeed' }}
      # Bound to 10 min so a stuck provision fails the run instead of
      # holding up the next cron firing. 15-min default in the script
      # is for the on-PR full lifecycle where we have more headroom.
@@ -88,37 +134,79 @@ jobs:
      E2E_KEEP_ORG: ${{ github.event.inputs.keep_org == 'true' && '1' || '' }}
      MOLECULE_CP_URL: ${{ vars.STAGING_CP_URL || 'https://staging-api.moleculesai.app' }}
      MOLECULE_ADMIN_TOKEN: ${{ secrets.CP_STAGING_ADMIN_API_TOKEN }}
-      # Provisioned tenant's default model (langgraph: openai:gpt-4.1-mini)
-      # needs OPENAI_API_KEY at first call. Sibling workflows
-      # e2e-staging-saas.yml + canary-staging.yml use the same secret;
-      # without this wire-up the tenant boots, accepts a2a messages,
-      # then returns "Could not resolve authentication method" — masked
-      # earlier by the a2a-sdk task-mode contract bugs PR #2558+#2563
-      # fixed. tests/e2e/test_staging_full_saas.sh:325 reads this and
-      # persists it as a workspace_secret on tenant create.
+      # MiniMax key is the canary's PRIMARY auth path. claude-code
+      # template's `minimax` provider routes ANTHROPIC_BASE_URL to
+      # api.minimax.io/anthropic and reads MINIMAX_API_KEY at boot.
+      # tests/e2e/test_staging_full_saas.sh branches SECRETS_JSON on
+      # which key is present — MiniMax wins when set.
+      E2E_MINIMAX_API_KEY: ${{ secrets.MOLECULE_STAGING_MINIMAX_API_KEY }}
+      # Direct-Anthropic alternative for operators who don't want to
+      # set up a MiniMax account (priority below MiniMax — first
+      # non-empty wins in test_staging_full_saas.sh's secrets-injection
+      # block). See #2578 PR comment for the rationale.
+      E2E_ANTHROPIC_API_KEY: ${{ secrets.MOLECULE_STAGING_ANTHROPIC_API_KEY }}
+      # OpenAI fallback — kept wired so operators can dispatch with
+      # E2E_RUNTIME=langgraph or =hermes and still have a working
+      # canary path. The script picks the right blob shape based on
+      # which key is non-empty.
      E2E_OPENAI_API_KEY: ${{ secrets.MOLECULE_STAGING_OPENAI_KEY }}
    steps:
      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2

-      - name: Verify required secret present
+      - name: Verify required secrets present
        run: |
-          # Schedule-vs-dispatch hardening (mirrors the sweep-cf-* and
-          # redeploy-tenants-on-* workflows): hard-fail on missing secret
-          # for cron firing so a misconfigured-repo doesn't silently
-          # report green while doing nothing. Soft-skip on operator
-          # dispatch — operators can dispatch ad-hoc to verify a fix
-          # without setting up the secret first.
+          # Hard-fail on missing secret REGARDLESS of trigger. Previously
+          # this step soft-skipped on workflow_dispatch via `exit 0`, but
+          # `exit 0` only ends the STEP — subsequent steps still ran with
+          # the empty secret, the synth script fell through to the wrong
+          # SECRETS_JSON branch, and the canary failed 5 min later with a
+          # confusing "Agent error (Exception)" instead of the clean
+          # "secret missing" message at the top. Caught 2026-05-04 by
+          # dispatched run 25296530706: claude-code + missing MINIMAX
+          # silently used OpenAI keys but kept model=MiniMax-M2.7, then
+          # the workspace 401'd against MiniMax once it tried to call.
+          # Fix: exit 1 in both cron and dispatch paths. Operators who
+          # want to verify a YAML change without setting up the secret
+          # can read the verify-secrets step's stderr — the failure is
+          # itself the verification signal.
          if [ -z "${MOLECULE_ADMIN_TOKEN:-}" ]; then
-            if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
-              echo "::warning::CP_STAGING_ADMIN_API_TOKEN not set — synth E2E cannot run"
-              echo "::warning::Set it at Settings → Secrets and Variables → Actions"
-              exit 0
-            fi
            echo "::error::CP_STAGING_ADMIN_API_TOKEN secret missing — synth E2E cannot run"
            echo "::error::Set it at Settings → Secrets and Variables → Actions; pull from staging-CP's CP_ADMIN_API_TOKEN env in Railway."
            exit 1
          fi

+          # LLM-key requirement is per-runtime: claude-code accepts
+          # EITHER MiniMax OR direct-Anthropic (whichever is set first),
+          # langgraph + hermes use OpenAI (MOLECULE_STAGING_OPENAI_KEY).
+          case "${E2E_RUNTIME}" in
+            claude-code)
+              if [ -n "${E2E_MINIMAX_API_KEY:-}" ]; then
+                required_secret_name="MOLECULE_STAGING_MINIMAX_API_KEY"
+                required_secret_value="${E2E_MINIMAX_API_KEY}"
+              elif [ -n "${E2E_ANTHROPIC_API_KEY:-}" ]; then
+                required_secret_name="MOLECULE_STAGING_ANTHROPIC_API_KEY"
+                required_secret_value="${E2E_ANTHROPIC_API_KEY}"
+              else
+                required_secret_name="MOLECULE_STAGING_MINIMAX_API_KEY or MOLECULE_STAGING_ANTHROPIC_API_KEY"
+                required_secret_value=""
+              fi
+              ;;
+            langgraph|hermes)
+              required_secret_name="MOLECULE_STAGING_OPENAI_KEY"
+              required_secret_value="${E2E_OPENAI_API_KEY:-}"
+              ;;
+            *)
+              echo "::warning::Unknown E2E_RUNTIME='${E2E_RUNTIME}' — skipping LLM-key check"
+              required_secret_name=""
+              required_secret_value="present"
+              ;;
+          esac
+          if [ -n "$required_secret_name" ] && [ -z "$required_secret_value" ]; then
+            echo "::error::${required_secret_name} secret missing — runtime=${E2E_RUNTIME} cannot authenticate against its LLM provider"
+            echo "::error::Set it at Settings → Secrets and Variables → Actions, OR dispatch with a different runtime"
+            exit 1
+          fi
+
      - name: Install required tools
        run: |
          # The script depends on jq + curl (already on ubuntu-latest)
@@ -172,6 +172,9 @@ jobs:
      - name: Run poll-mode + since_id cursor E2E (#2339)
        if: needs.detect-changes.outputs.api == 'true'
        run: bash tests/e2e/test_poll_mode_e2e.sh
+      - name: Run poll-mode chat upload E2E (RFC #2891)
+        if: needs.detect-changes.outputs.api == 'true'
+        run: bash tests/e2e/test_poll_mode_chat_upload_e2e.sh
      - name: Dump platform log on failure
        if: failure() && needs.detect-changes.outputs.api == 'true'
        run: cat workspace-server/platform.log || true
@@ -184,8 +184,27 @@ jobs:
            exit 0
          fi
          echo "Deleting orphan tenant: $slug"
-          curl -sS -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
+          # Verify HTTP 2xx instead of `>/dev/null || true` swallowing
+          # failures. A 5xx or timeout previously looked identical to
+          # success, leaving the tenant alive for up to ~45 min until
+          # sweep-stale-e2e-orgs caught it. Surface failures as
+          # workflow warnings naming the slug. Don't `exit 1` — a single
+          # cleanup miss shouldn't fail-flag the canvas test when the
+          # actual smoke check passed; the sweeper is the safety net.
+          # See molecule-controlplane#420.
+          # Tempfile-routed -w + set +e/-e prevents curl-exit-code
+          # pollution of the captured status (lint-curl-status-capture.yml).
+          set +e
+          curl -sS -o /tmp/canvas-cleanup.out -w "%{http_code}" \
+            -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
            -H "Authorization: Bearer $ADMIN_TOKEN" \
            -H "Content-Type: application/json" \
-            -d "{\"confirm\":\"$slug\"}" >/dev/null || true
+            -d "{\"confirm\":\"$slug\"}" >/tmp/canvas-cleanup.code
+          set -e
+          code=$(cat /tmp/canvas-cleanup.code 2>/dev/null || echo "000")
+          if [ "$code" = "200" ] || [ "$code" = "204" ]; then
+            echo "[teardown] deleted $slug (HTTP $code)"
+          else
+            echo "::warning::canvas teardown for $slug returned HTTP $code — sweep-stale-e2e-orgs will catch it within ~45 min. Body: $(head -c 300 /tmp/canvas-cleanup.out 2>/dev/null)"
+          fi
          exit 0
@@ -153,12 +153,32 @@ jobs:
          if [ -n "$orgs" ]; then
            echo "Safety-net sweep: deleting leftover orgs:"
            echo "$orgs"
+            # Per-slug verified DELETE — see molecule-controlplane#420.
+            # `>/dev/null 2>&1` previously hid every failure; surface
+            # non-2xx as workflow warnings so the run page names what
+            # leaked. Sweeper catches the rest within ~45 min.
+            leaks=()
            for slug in $orgs; do
-              curl -sS -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
+              # Tempfile-routed -w + set +e/-e prevents curl-exit-code
+              # pollution of the captured status (lint-curl-status-capture.yml).
+              set +e
+              curl -sS -o /tmp/external-cleanup.out -w "%{http_code}" \
+                -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
                -H "Authorization: Bearer $ADMIN_TOKEN" \
                -H "Content-Type: application/json" \
-                -d "{\"confirm\":\"$slug\"}" >/dev/null 2>&1
+                -d "{\"confirm\":\"$slug\"}" >/tmp/external-cleanup.code
+              set -e
+              code=$(cat /tmp/external-cleanup.code 2>/dev/null || echo "000")
+              if [ "$code" = "200" ] || [ "$code" = "204" ]; then
+                echo "[teardown] deleted $slug (HTTP $code)"
+              else
+                echo "::warning::external teardown for $slug returned HTTP $code — sweep-stale-e2e-orgs will catch it within ~45 min. Body: $(head -c 300 /tmp/external-cleanup.out 2>/dev/null)"
+                leaks+=("$slug")
+              fi
            done
+            if [ ${#leaks[@]} -gt 0 ]; then
+              echo "::warning::external teardown left ${#leaks[@]} leak(s): ${leaks[*]}"
+            fi
          else
            echo "Safety-net sweep: no leftover orgs to clean."
          fi
@@ -48,9 +48,9 @@ on:
  workflow_dispatch:
    inputs:
      runtime:
-        description: "Runtime to test (hermes | claude-code | langgraph)"
+        description: "Runtime to test (claude-code [default, MiniMax] | hermes [OpenAI] | langgraph [OpenAI])"
        required: false
-        default: "hermes"
+        default: "claude-code"
      keep_org:
        description: "Skip teardown for debugging (only use via manual dispatch!)"
        required: false
@@ -83,11 +83,32 @@ jobs:
      # retrieval + teardown. Configure in
      # Settings → Secrets and variables → Actions → Repository secrets.
      MOLECULE_ADMIN_TOKEN: ${{ secrets.MOLECULE_STAGING_ADMIN_TOKEN }}
-      # OpenAI key for workspace LLM calls (section 8 A2A). Without it,
-      # Hermes runtime crashes at boot with "No provider API key found".
-      # Configure at Settings → Secrets → Actions → MOLECULE_STAGING_OPENAI_KEY.
+      # MiniMax is the PRIMARY LLM auth path post-2026-05-04. Switched
+      # from hermes+OpenAI default after #2578 (the staging OpenAI key
+      # account went over quota and stayed dead for 36+ hours, taking
+      # the full-lifecycle E2E red on every provisioning-critical push).
+      # claude-code template's `minimax` provider routes
+      # ANTHROPIC_BASE_URL to api.minimax.io/anthropic and reads
+      # MINIMAX_API_KEY at boot — separate billing account so an
+      # OpenAI quota collapse no longer wedges the gate. Mirrors the
+      # canary-staging.yml + continuous-synth-e2e.yml migrations.
+      E2E_MINIMAX_API_KEY: ${{ secrets.MOLECULE_STAGING_MINIMAX_API_KEY }}
+      # Direct-Anthropic alternative for operators who don't want to
+      # set up a MiniMax account (priority below MiniMax — first
+      # non-empty wins in test_staging_full_saas.sh's secrets-injection
+      # block). See #2578 PR comment for the rationale.
+      E2E_ANTHROPIC_API_KEY: ${{ secrets.MOLECULE_STAGING_ANTHROPIC_API_KEY }}
+      # OpenAI fallback — kept wired so an operator-dispatched run with
+      # E2E_RUNTIME=hermes or =langgraph via workflow_dispatch can still
+      # exercise the OpenAI path.
      E2E_OPENAI_API_KEY: ${{ secrets.MOLECULE_STAGING_OPENAI_KEY }}
-      E2E_RUNTIME: ${{ github.event.inputs.runtime || 'hermes' }}
+      E2E_RUNTIME: ${{ github.event.inputs.runtime || 'claude-code' }}
+      # Pin the model when running on the default claude-code path —
+      # the per-runtime default ("sonnet") routes to direct Anthropic
+      # and defeats the cost saving. Operators can override via the
+      # workflow_dispatch flow (no input wired here yet — runtime
+      # override is enough for ad-hoc).
+      E2E_MODEL_SLUG: ${{ github.event.inputs.runtime == 'hermes' && 'openai/gpt-4o' || github.event.inputs.runtime == 'langgraph' && 'openai:gpt-4o' || 'MiniMax-M2.7-highspeed' }}
      E2E_RUN_ID: "${{ github.run_id }}-${{ github.run_attempt }}"
      E2E_KEEP_ORG: ${{ github.event.inputs.keep_org && '1' || '0' }}

@@ -102,13 +123,45 @@ jobs:
          fi
          echo "Admin token present ✓"

-      - name: Verify OpenAI key present
+      - name: Verify LLM key present
        run: |
-          if [ -z "$E2E_OPENAI_API_KEY" ]; then
-            echo "::error::MOLECULE_STAGING_OPENAI_KEY secret not set — workspaces will fail at boot with 'No provider API key found'"
+          # Per-runtime key check — claude-code uses MiniMax; hermes /
+          # langgraph (operator-dispatched only) use OpenAI. Hard-fail
+          # rather than soft-skip per #2578's lesson — empty key
+          # silently falls through to the wrong SECRETS_JSON branch and
+          # produces a confusing auth error 5 min later instead of the
+          # clean "secret missing" message at the top.
+          case "${E2E_RUNTIME}" in
+            claude-code)
+              # Either MiniMax OR direct-Anthropic works — first
+              # non-empty wins in the test script's secrets-injection
+              # priority chain.
+              if [ -n "${E2E_MINIMAX_API_KEY:-}" ]; then
+                required_secret_name="MOLECULE_STAGING_MINIMAX_API_KEY"
+                required_secret_value="${E2E_MINIMAX_API_KEY}"
+              elif [ -n "${E2E_ANTHROPIC_API_KEY:-}" ]; then
+                required_secret_name="MOLECULE_STAGING_ANTHROPIC_API_KEY"
+                required_secret_value="${E2E_ANTHROPIC_API_KEY}"
+              else
+                required_secret_name="MOLECULE_STAGING_MINIMAX_API_KEY or MOLECULE_STAGING_ANTHROPIC_API_KEY"
+                required_secret_value=""
+              fi
+              ;;
+            langgraph|hermes)
+              required_secret_name="MOLECULE_STAGING_OPENAI_KEY"
+              required_secret_value="${E2E_OPENAI_API_KEY:-}"
+              ;;
+            *)
+              echo "::warning::Unknown E2E_RUNTIME='${E2E_RUNTIME}' — skipping LLM-key check"
+              required_secret_name=""
+              required_secret_value="present"
+              ;;
+          esac
+          if [ -n "$required_secret_name" ] && [ -z "$required_secret_value" ]; then
+            echo "::error::${required_secret_name} secret not set for runtime=${E2E_RUNTIME} — workspaces will fail at boot with 'No provider API key found'"
            exit 2
          fi
-          echo "OpenAI key present ✓ (len=${#E2E_OPENAI_API_KEY})"
+          echo "LLM key present ✓ (runtime=${E2E_RUNTIME}, key=${required_secret_name}, len=${#required_secret_value})"

      - name: CP staging health preflight
        run: |
@@ -164,11 +217,31 @@ jobs:
                        and o.get('instance_status') not in ('purged',)]
          print('\n'.join(candidates))
          " 2>/dev/null)
+          # Per-slug verified DELETE (was `>/dev/null || true` — see
+          # molecule-controlplane#420). Surface non-2xx as a workflow
+          # warning naming the leaked slug; don't exit 1 (sweeper is
+          # the safety net within ~45 min).
+          leaks=()
          for slug in $orgs; do
            echo "Safety-net teardown: $slug"
-            curl -sS -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
+            # Tempfile-routed -w + set +e/-e prevents curl-exit-code
+            # pollution of the captured status (lint-curl-status-capture.yml).
+            set +e
+            curl -sS -o /tmp/saas-cleanup.out -w "%{http_code}" \
+              -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
              -H "Authorization: Bearer $ADMIN_TOKEN" \
              -H "Content-Type: application/json" \
-              -d "{\"confirm\":\"$slug\"}" >/dev/null || true
+              -d "{\"confirm\":\"$slug\"}" >/tmp/saas-cleanup.code
+            set -e
+            code=$(cat /tmp/saas-cleanup.code 2>/dev/null || echo "000")
+            if [ "$code" = "200" ] || [ "$code" = "204" ]; then
+              echo "[teardown] deleted $slug (HTTP $code)"
+            else
+              echo "::warning::saas teardown for $slug returned HTTP $code — sweep-stale-e2e-orgs will catch it within ~45 min. Body: $(head -c 300 /tmp/saas-cleanup.out 2>/dev/null)"
+              leaks+=("$slug")
+            fi
          done
+          if [ ${#leaks[@]} -gt 0 ]; then
+            echo "::warning::saas teardown left ${#leaks[@]} leak(s): ${leaks[*]}"
+          fi
          exit 0
@@ -143,10 +143,29 @@ jobs:
                        and o.get('status') not in ('purged',)]
          print('\n'.join(candidates))
          " 2>/dev/null)
+          # Per-slug verified DELETE — see molecule-controlplane#420.
+          # Failures surface as workflow warnings; the sweeper is the
+          # safety net within ~45 min.
+          leaks=()
          for slug in $orgs; do
-            curl -sS -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
+            # Tempfile-routed -w + set +e/-e prevents curl-exit-code
+            # pollution of the captured status (lint-curl-status-capture.yml).
+            set +e
+            curl -sS -o /tmp/sanity-cleanup.out -w "%{http_code}" \
+              -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
              -H "Authorization: Bearer $ADMIN_TOKEN" \
              -H "Content-Type: application/json" \
-              -d "{\"confirm\":\"$slug\"}" >/dev/null || true
+              -d "{\"confirm\":\"$slug\"}" >/tmp/sanity-cleanup.code
+            set -e
+            code=$(cat /tmp/sanity-cleanup.code 2>/dev/null || echo "000")
+            if [ "$code" = "200" ] || [ "$code" = "204" ]; then
+              echo "[teardown] deleted $slug (HTTP $code)"
+            else
+              echo "::warning::sanity teardown for $slug returned HTTP $code — sweep-stale-e2e-orgs will catch it within ~45 min. Body: $(head -c 300 /tmp/sanity-cleanup.out 2>/dev/null)"
+              leaks+=("$slug")
+            fi
          done
+          if [ ${#leaks[@]} -gt 0 ]; then
+            echo "::warning::sanity teardown left ${#leaks[@]} leak(s): ${leaks[*]}"
+          fi
          exit 0
@@ -0,0 +1,160 @@
+name: Handlers Postgres Integration
+
+# Real-Postgres integration tests for workspace-server/internal/handlers/.
+# Triggered on every PR/push that touches the handlers package.
+#
+# Why this workflow exists
+# ------------------------
+# Strict-sqlmock unit tests pin which SQL statements fire — they're fast
+# and let us iterate without a DB. But sqlmock CANNOT detect bugs that
+# depend on the row state AFTER the SQL runs. The result_preview-lost
+# bug shipped to staging in PR #2854 because every unit test was
+# satisfied with "an UPDATE statement fired" — none verified the row's
+# preview field actually landed. The local-postgres E2E that retrofit
+# self-review caught it took 2 minutes to set up and would have caught
+# the bug at PR-time.
+#
+# This job spins a Postgres service container, applies the migration,
+# and runs `go test -tags=integration` against a live DB. Required
+# check on staging branch protection — backend handler PRs cannot
+# merge without a real-DB regression gate.
+#
+# Cost: ~30s job (postgres pull from GH cache + go build + 4 tests).
+
+on:
+  push:
+    branches: [main, staging]
+  pull_request:
+    branches: [main, staging]
+  merge_group:
+    types: [checks_requested]
+  workflow_dispatch:
+
+concurrency:
+  group: handlers-pg-integ-${{ github.event.pull_request.head.sha || github.sha }}
+  cancel-in-progress: false
+
+jobs:
+  detect-changes:
+    name: detect-changes
+    runs-on: ubuntu-latest
+    outputs:
+      handlers: ${{ steps.filter.outputs.handlers }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.0.1
+        id: filter
+        with:
+          filters: |
+            handlers:
+              - 'workspace-server/internal/handlers/**'
+              - 'workspace-server/internal/wsauth/**'
+              - 'workspace-server/migrations/**'
+              - '.github/workflows/handlers-postgres-integration.yml'
+
+  # Single-job-with-per-step-if pattern: always runs to satisfy the
+  # required-check name on branch protection; real work gates on the
+  # paths filter. See ci.yml's Platform (Go) for the same shape.
+  integration:
+    name: Handlers Postgres Integration
+    needs: detect-changes
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:15-alpine
+        env:
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: molecule
+        ports:
+          - 5432:5432
+        # GHA spins this with --health-cmd built in for postgres images.
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+    defaults:
+      run:
+        working-directory: workspace-server
+    steps:
+      - if: needs.detect-changes.outputs.handlers != 'true'
+        working-directory: .
+        run: echo "No handlers/migrations changes — skipping; this job always runs to satisfy the required-check name."
+
+      - if: needs.detect-changes.outputs.handlers == 'true'
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - if: needs.detect-changes.outputs.handlers == 'true'
+        uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+        with:
+          go-version: 'stable'
+
+      - if: needs.detect-changes.outputs.handlers == 'true'
+        name: Apply migrations to Postgres service
+        env:
+          PGPASSWORD: test
+        run: |
+          # Wait for postgres to actually accept connections (the
+          # GHA --health-cmd is best-effort but psql can still race).
+          for i in {1..15}; do
+            if pg_isready -h localhost -p 5432 -U postgres -q; then break; fi
+            echo "waiting for postgres..."; sleep 2
+          done
+
+          # Apply every .up.sql in lexicographic order with
+          # ON_ERROR_STOP=0 — failing migrations are SKIPPED rather than
+          # blocking the suite. This handles the current schema state
+          # where a few historical migrations (e.g. 017_memories_fts_*)
+          # depend on tables that were later renamed/dropped and so
+          # cannot replay from scratch. The migrations that DO succeed
+          # land their tables, which is sufficient for the integration
+          # tests in handlers/.
+          #
+          # Why not maintain a curated allowlist: every new migration
+          # touching a handlers/-tested table would have to update this
+          # workflow. With apply-all-or-skip, a future migration that
+          # adds a column to delegations runs automatically (its base
+          # table 049_delegations.up.sql already succeeded above it in
+          # the order). Operators only need to revisit this if the
+          # migration chain becomes legitimately replayable end-to-end.
+          #
+          # Per-migration result is logged so a failed migration that
+          # SHOULD have been replayable surfaces in the CI log instead
+          # of silently failing.
+          set +e
+          for migration in migrations/*.up.sql; do
+            if psql -h localhost -U postgres -d molecule -v ON_ERROR_STOP=1 \
+                  -f "$migration" >/dev/null 2>&1; then
+              echo "✓ $(basename "$migration")"
+            else
+              echo "⊘ $(basename "$migration") (skipped — see comment in workflow)"
+            fi
+          done
+          set -e
+
+          # Sanity: the delegations table MUST exist for the integration
+          # tests to be meaningful. Hard-fail if 049 didn't land — that
+          # would be a real regression we want loud.
+          if ! psql -h localhost -U postgres -d molecule -tA \
+              -c "SELECT 1 FROM information_schema.tables WHERE table_name = 'delegations'" \
+              | grep -q 1; then
+            echo "::error::delegations table missing after migration replay — handler integration tests would be meaningless"
+            exit 1
+          fi
+          echo "✓ delegations table present"
+
+      - if: needs.detect-changes.outputs.handlers == 'true'
+        name: Run integration tests
+        env:
+          INTEGRATION_DB_URL: postgres://postgres:test@localhost:5432/molecule?sslmode=disable
+        run: |
+          go test -tags=integration -timeout 5m -v ./internal/handlers/ -run "^TestIntegration_"
+
+      - if: needs.detect-changes.outputs.handlers == 'true' && failure()
+        name: Diagnostic dump on failure
+        env:
+          PGPASSWORD: test
+        run: |
+          echo "::group::delegations table state"
+          psql -h localhost -U postgres -d molecule -c "SELECT * FROM delegations LIMIT 50;" || true
+          echo "::endgroup::"
@@ -0,0 +1,94 @@
+name: Lint curl status-code capture
+
+# Pins the workflow-bash anti-pattern that produced "HTTP 000000" on the
+# 2026-05-04 redeploy-tenants-on-main run for sha 2b862f6:
+#
+#   HTTP_CODE=$(curl ... -w '%{http_code}' ... || echo "000")
+#
+# When curl exits non-zero (connection reset → 56, --fail-with-body 4xx/5xx
+# → 22), the `-w '%{http_code}'` already wrote a status to stdout — usually
+# "000" for connection failures or the actual code for HTTP errors. The
+# `|| echo "000"` then fires AND appends ANOTHER "000" to the captured
+# stdout, producing values like "000000" or "409000" that fail string
+# comparisons against "200" while looking superficially right.
+#
+# Same class of bug the synth-E2E §7c gate hit twice (PRs #2779/#2783 +
+# #2797). Memory: feedback_curl_status_capture_pollution.md.
+#
+# Fix shape (route -w into a tempfile so curl's exit code can't pollute):
+#
+#   set +e
+#   curl ... -w '%{http_code}' >code.txt 2>/dev/null
+#   set -e
+#   HTTP_CODE=$(cat code.txt 2>/dev/null)
+#   [ -z "$HTTP_CODE" ] && HTTP_CODE="000"
+
+on:
+  pull_request:
+    paths: ['.github/workflows/**']
+  push:
+    branches: [main, staging]
+    paths: ['.github/workflows/**']
+  merge_group:
+    types: [checks_requested]
+
+jobs:
+  scan:
+    name: Scan workflows for curl status-capture pollution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Find curl ... -w '%{http_code}' ... || echo "000" subshells
+        run: |
+          set -uo pipefail
+          # Multi-line aware: look for `$(curl ... -w '%{http_code}' ... || echo "000")`
+          # subshell where the entire command-substitution wraps a curl that
+          # ends with `|| echo "000"`. Must distinguish from the SAFE shape
+          # `$(cat tempfile 2>/dev/null || echo "000")` — `cat` with a missing
+          # tempfile produces empty stdout, no pollution.
+          python3 <<'PY'
+          import os, re, sys, glob
+
+          BAD_FILES = []
+
+          # Match the buggy substitution across newlines: $(curl ... -w '%{http_code}' ... || echo "000")
+          # The `\\n` is the bash line-continuation that lets curl flags span lines.
+          # We collapse continuation lines first, then look for the single-line bad pattern.
+          PATTERN = re.compile(
+              r'\$\(\s*curl\b[^)]*-w\s*[\'"]%\{http_code\}[\'"][^)]*\|\|\s*echo\s+"000"\s*\)',
+              re.DOTALL,
+          )
+
+          # Self-skip: this lint workflow contains the literal anti-pattern in
+          # its own docstring — that's intentional, not a bug.
+          SELF = ".github/workflows/lint-curl-status-capture.yml"
+
+          for f in sorted(glob.glob(".github/workflows/*.yml")):
+              if f == SELF:
+                  continue
+              with open(f) as fh:
+                  content = fh.read()
+              # Collapse bash line-continuations (\\\n + leading whitespace)
+              # into a single logical line so the regex can see the full
+              # curl invocation as one chunk.
+              flat = re.sub(r'\\\s*\n\s*', ' ', content)
+              for m in PATTERN.finditer(flat):
+                  BAD_FILES.append((f, m.group(0)[:120]))
+
+          if not BAD_FILES:
+              print("✓ No curl-status-capture pollution patterns detected")
+              sys.exit(0)
+
+          print(f"::error::Found {len(BAD_FILES)} curl-status-capture pollution site(s):")
+          for f, snippet in BAD_FILES:
+              print(f"::error file={f}::Curl status-capture pollution: '|| echo \"000\"' inside a $(curl ... -w '%{{http_code}}' ...) subshell. On non-2xx or connection failure, curl's -w writes a status, then exits non-zero, then the || echo appends another '000' — producing 'HTTP 000000' or '409000' that fails comparisons silently. Fix: route -w into a tempfile so the exit code can't pollute stdout. See memory feedback_curl_status_capture_pollution.md.")
+              print(f"   matched: {snippet}…")
+          print()
+          print("Fix template:")
+          print('  set +e')
+          print('  curl ... -w \'%{http_code}\' >code.txt 2>/dev/null')
+          print('  set -e')
+          print('  HTTP_CODE=$(cat code.txt 2>/dev/null)')
+          print('  [ -z "$HTTP_CODE" ] && HTTP_CODE="000"')
+          sys.exit(1)
+          PY
@@ -184,12 +184,29 @@ jobs:
          echo "  body: $BODY"

          HTTP_RESPONSE=$(mktemp)
-          HTTP_CODE=$(curl -sS -o "$HTTP_RESPONSE" -w '%{http_code}' \
+          HTTP_CODE_FILE=$(mktemp)
+          # Route -w into its own tempfile so curl's exit code (e.g. 56
+          # on connection-reset, 22 on --fail-with-body 4xx/5xx) can't
+          # pollute the captured stdout. The previous inline-substitution
+          # shape produced "000000" on connection reset (curl wrote
+          # "000" via -w, then the inline echo-fallback appended another
+          # "000") — caught on the 2026-05-04 redeploy of sha 2b862f6.
+          # set +e/-e keeps the non-zero curl exit from tripping the
+          # outer pipeline. See lint-curl-status-capture.yml for the
+          # CI gate that pins this fix shape.
+          set +e
+          curl -sS -o "$HTTP_RESPONSE" -w '%{http_code}' \
            -m 1200 \
            -H "Authorization: Bearer $CP_ADMIN_API_TOKEN" \
            -H "Content-Type: application/json" \
            -X POST "$CP_URL/cp/admin/tenants/redeploy-fleet" \
-            -d "$BODY" || echo "000")
+            -d "$BODY" >"$HTTP_CODE_FILE"
+          set -e
+          # Stderr from curl (e.g. dial errors with -sS) goes to the runner
+          # log so operators can see WHY a connection failed. Stdout is
+          # captured to $HTTP_CODE_FILE because that's where -w writes.
+          HTTP_CODE=$(cat "$HTTP_CODE_FILE" 2>/dev/null || echo "000")
+          [ -z "$HTTP_CODE" ] && HTTP_CODE="000"

          echo "HTTP $HTTP_CODE"
          cat "$HTTP_RESPONSE" | jq . || cat "$HTTP_RESPONSE"
@@ -146,12 +146,26 @@ jobs:
          echo "  body: $BODY"

          HTTP_RESPONSE=$(mktemp)
-          HTTP_CODE=$(curl -sS -o "$HTTP_RESPONSE" -w '%{http_code}' \
+          HTTP_CODE_FILE=$(mktemp)
+          # Route -w into its own tempfile so curl's exit code (e.g. 56
+          # on connection-reset) can't pollute the captured stdout. The
+          # previous inline-substitution shape produced "000000" on
+          # connection reset — caught on main variant 2026-05-04
+          # redeploying sha 2b862f6. Same fix shape as the synth-E2E
+          # §9c gate (PR #2797). See lint-curl-status-capture.yml for
+          # the CI gate that pins this fix shape.
+          set +e
+          curl -sS -o "$HTTP_RESPONSE" -w '%{http_code}' \
            -m 1200 \
            -H "Authorization: Bearer $CP_STAGING_ADMIN_API_TOKEN" \
            -H "Content-Type: application/json" \
            -X POST "$CP_URL/cp/admin/tenants/redeploy-fleet" \
-            -d "$BODY" || echo "000")
+            -d "$BODY" >"$HTTP_CODE_FILE"
+          set -e
+          # Stderr from curl (-sS shows dial errors etc.) goes to the
+          # runner log so operators can see WHY a connection failed.
+          HTTP_CODE=$(cat "$HTTP_CODE_FILE" 2>/dev/null || echo "000")
+          [ -z "$HTTP_CODE" ] && HTTP_CODE="000"

          echo "HTTP $HTTP_CODE"
          cat "$HTTP_RESPONSE" | jq . || cat "$HTTP_RESPONSE"
@@ -43,7 +43,20 @@ on:
    types: [checks_requested]

 concurrency:
-  group: ${{ github.workflow }}-${{ github.event.pull_request.head.sha || github.sha }}
+  # Include event_name so a PR sync (event=pull_request) and the
+  # subsequent staging push (event=push) on the SAME merge SHA don't
+  # collide in one group. Without event_name, both runs hashed to
+  # the same key and cancel-in-progress=true cancelled whichever
+  # arrived second — usually the push run, which staging branch-
+  # protection then sees as a CANCELLED required check and refuses
+  # to mark merged. Caught 2026-05-05 across PR #2869's runs (run
+  # ids 25371863455 / 25371811486 / 25371078157 / 25370403142 — every
+  # staging push run cancelled, every matching PR run green).
+  #
+  # Per memory `feedback_concurrency_group_per_sha.md` — same drift
+  # class that broke auto-promote-staging on 2026-04-28. Pin invariant:
+  # event_name + sha is the minimum unique key for these workflows.
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.event.pull_request.head.sha || github.sha }}
  cancel-in-progress: true

 jobs:
@@ -25,16 +25,23 @@ name: Sweep stale e2e-* orgs (staging)

 on:
  schedule:
-    # Every hour on the hour. E2E orgs are short-lived (~10-25 min wall
-    # clock from create to teardown). Anything older than the
-    # MAX_AGE_MINUTES threshold below is presumed dead.
-    - cron: '0 * * * *'
+    # Every 15 min. E2E orgs are short-lived (~8-25 min wall clock from
+    # create to teardown — canary is ~8 min, full SaaS ~25 min). The
+    # previous hourly + 120-min stale threshold meant a leaked tenant
+    # could keep an EC2 alive for up to 2 hours, eating ~2 vCPU per
+    # leak. Tightening the cadence + threshold reduces the worst-case
+    # leak window from 120 min to ~45 min (15-min sweep cadence + 30-min
+    # threshold) without risk of catching in-progress runs (the longest
+    # e2e run is the 25-min canary, well under the 30-min threshold).
+    # See molecule-controlplane#420 for the leak-class accounting that
+    # motivated this tightening.
+    - cron: '*/15 * * * *'
  workflow_dispatch:
    inputs:
      max_age_minutes:
-        description: "Delete e2e-* orgs older than N minutes (default 120)"
+        description: "Delete e2e-* orgs older than N minutes (default 30)"
        required: false
-        default: "120"
+        default: "30"
      dry_run:
        description: "Dry run only — list what would be deleted"
        required: false
@@ -58,7 +65,7 @@ jobs:
    env:
      MOLECULE_CP_URL: https://staging-api.moleculesai.app
      ADMIN_TOKEN: ${{ secrets.MOLECULE_STAGING_ADMIN_TOKEN }}
-      MAX_AGE_MINUTES: ${{ github.event.inputs.max_age_minutes || '120' }}
+      MAX_AGE_MINUTES: ${{ github.event.inputs.max_age_minutes || '30' }}
      DRY_RUN: ${{ github.event.inputs.dry_run || 'false' }}
      # Refuse to delete more than this many orgs in one tick. If the
      # CP DB is briefly empty (or the admin endpoint goes weird and
@@ -152,12 +159,18 @@ jobs:
            # The DELETE handler requires {"confirm": "<slug>"} matching
            # the URL slug — fat-finger guard. Idempotent: re-issuing
            # picks up via org_purges.last_step.
-            http_code=$(curl -sS -o /tmp/del_resp -w "%{http_code}" \
+            # Tempfile-routed -w + set +e/-e prevents curl-exit-code
+            # pollution of the captured status (lint-curl-status-capture.yml).
+            set +e
+            curl -sS -o /tmp/del_resp -w "%{http_code}" \
              --max-time 60 \
              -X DELETE "$MOLECULE_CP_URL/cp/admin/tenants/$slug" \
              -H "Authorization: Bearer $ADMIN_TOKEN" \
              -H "Content-Type: application/json" \
-              -d "{\"confirm\":\"$slug\"}" || echo "000")
+              -d "{\"confirm\":\"$slug\"}" >/tmp/del_code
+            set -e
+            # Stderr from curl (-sS shows dial errors etc.) goes to runner log.
+            http_code=$(cat /tmp/del_code 2>/dev/null || echo "000")
            if [ "$http_code" = "200" ] || [ "$http_code" = "204" ]; then
              deleted=$((deleted+1))
              echo "  deleted: $slug"
@@ -1,7 +1,7 @@
 # Coverage Floor

-CI enforces three coverage gates on `workspace-server` (Go). All defined in
-`.github/workflows/ci.yml` → `platform-build` job.
+CI enforces coverage gates on two surfaces — `workspace-server` (Go) and
+`workspace/` (Python). All defined in `.github/workflows/ci.yml`.

 ## Current floors (2026-04-23)

@@ -76,3 +76,51 @@ This gate makes "no untested critical paths merged" a mechanical property of
 the CI, not a behavioural property of QA agents or individual reviewers —
 which is the only way to make it survive fleet outages, agent rotations, or
 QA process changes.
+
+## Python (workspace/) — added 2026-05-04 from #2790
+
+The Python side has its own gates in the `python-lint` job:
+
+| Gate | Threshold | Where |
+|---|---|---|
+| **Total floor** | `86%` | `workspace/pytest.ini` `--cov-fail-under=86` (issue #1817) |
+| **Critical-path per-file floor** | `75%` | Inline shell step after the pytest run |
+
+### Critical-path Python files
+
+These handle multi-tenant routing, auth tokens, and inbox dispatch. A
+coverage drop here is the same risk shape as a Go-side `tokens*` /
+`secrets*` file regressing below 10%.
+
+- `workspace/a2a_mcp_server.py` — MCP dispatcher (PR #2766 / #2771)
+- `workspace/mcp_cli.py` — molecule-mcp standalone CLI entry
+- `workspace/a2a_tools.py` — workspace-scoped tool implementations
+- `workspace/inbox.py` — multi-workspace inbox + per-workspace cursors
+- `workspace/platform_auth.py` — per-workspace token resolver
+
+### Why 75% (vs 86% total)
+
+The total floor averages ~6000 lines across `workspace/`. A single MCP
+file could drop to ~50% with no CI complaint as long as other modules
+compensate. The per-file floor closes that distribution gap. 75% sits
+below current actuals (80–96% as of 2026-05-04) — strictly additive,
+no existing PR fails.
+
+### Python ratchet plan
+
+| Date | Total | Per-file critical | Notes |
+|---|---|---|---|
+| 2026-05-04 | 86% | 75% | Initial gate (this file). |
+| 2026-06-04 | 86% | 80% | First ratchet — at-floor files must catch up. |
+| 2026-07-04 | 88% | 85% | |
+| 2026-08-04 | 90% | 90% | Target steady-state. |
+
+### Why this Python gate exists
+
+Issue #2790, after the PR #2766 → PR #2771 cycle. PR #2766 added
+multi-workspace routing through `a2a_tools.py` + `a2a_mcp_server.py`,
+shipped to main with green CI, but the dispatcher silently dropped a
+load-bearing kwarg for 4 of 9 tools — caught only by post-merge code
+review. The structural drift gate (`test_dispatcher_schema_drift.py`,
+PR #2791) catches the schema↔dispatcher mismatch class; this floor
+catches the broader "MCP-critical file regressed" class.
@@ -169,7 +169,17 @@ export default async function globalSetup(_config: FullConfig): Promise<void> {
        orgID = row.id;
        return true;
      }
-      if (row.instance_status === "failed") throw new Error(`provision failed: ${slug}`);
+      if (row.instance_status === "failed") {
+        // Dump every diagnostic field the admin row carries — boot stage,
+        // last error, terraform/SSM state, etc. The bare slug message used
+        // to surface ZERO context, so triaging a failed provision meant
+        // re-running locally to repro. Now the failure log carries enough
+        // to point at the right subsystem (CP/AWS/SSM/runtime) without a
+        // second round-trip.
+        throw new Error(
+          `provision failed: ${slug} — admin-orgs row: ${JSON.stringify(row)}`,
+        );
+      }
      return null;
    },
    PROVISION_TIMEOUT_MS,
@@ -249,7 +259,17 @@ export default async function globalSetup(_config: FullConfig): Promise<void> {
      if (r.status !== 200) return null;
      if (r.body?.status === "online") return true;
      if (r.body?.status === "failed") {
-        throw new Error(`Workspace failed: ${r.body.last_sample_error || ""}`);
+        // last_sample_error is often empty when the failure happens before
+        // the agent emits a sample (e.g. boot crash, image pull error,
+        // missing PYTHONPATH, OpenAI quota at startup). Dumping the full
+        // body gives triage the boot_stage / last_error / image fields it
+        // needs without a second probe. Otherwise this propagates as a
+        // bare "Workspace failed: " — the exact useless message that
+        // sent #2632 to the issue tracker.
+        const detail = r.body.last_sample_error
+          ? r.body.last_sample_error
+          : `(no last_sample_error) full body: ${JSON.stringify(r.body)}`;
+        throw new Error(`Workspace failed: ${detail}`);
      }
      return null;
    },
@@ -1,6 +1,15 @@
@import "tailwindcss";
@plugin "@tailwindcss/typography";

+/*
+ * Tailwind v4 defaults the `dark:` variant to `prefers-color-scheme: dark`.
+ * Our theme switcher writes `data-theme="dark"` on <html> instead (so user
+ * choice via the toggle wins over OS preference). Re-bind `dark:` to that
+ * attribute so component classes like `dark:bg-zinc-800` track the same
+ * source of truth as the `[data-theme="dark"]` token overrides below.
+ */
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));
+
 /*
 * Load order:
 *   1. Tailwind core (v4) — provides preflight + utility generation.
@@ -18,7 +18,7 @@
 // quick bounce between signup and either Checkout or the tenant UI.

 import { useEffect, useState } from "react";
-import { fetchSession, redirectToLogin, type Session } from "@/lib/auth";
+import { fetchSession, redirectToLogin, signOut, type Session } from "@/lib/auth";
 import { PLATFORM_URL } from "@/lib/api";
 import { formatCredits, pillTone, bannerKind } from "@/lib/credits";
 import { TermsGate } from "@/components/TermsGate";
@@ -129,7 +129,7 @@ export default function OrgsPage() {
    return <EmptyState banner={justCheckedOut ? <CheckoutBanner /> : null} />;
  }
  return (
-    <Shell>
+    <Shell session={session}>
      {justCheckedOut && <CheckoutBanner />}
      <ul className="space-y-3">
        {orgs.map((o) => (
@@ -160,11 +160,21 @@ function CheckoutBanner() {
  );
 }

-function Shell({ children }: { children: React.ReactNode }) {
+function Shell({
+  children,
+  session,
+}: {
+  children: React.ReactNode;
+  // Optional: when present, the header renders the signed-in email +
+  // a Sign-out button. The empty-state Shell call doesn't have a
+  // session in scope, so accept null and skip the header chrome there.
+  session?: Session | null;
+}) {
  return (
    <main className="min-h-screen bg-surface text-ink">
      <TermsGate>
        <div className="mx-auto max-w-2xl px-6 pt-20 pb-12">
+          {session ? <AccountBar session={session} /> : null}
          <h1 className="text-3xl font-bold text-ink">Your organizations</h1>
          <p className="mt-2 text-ink-mid">
            Each org is an isolated Molecule workspace.
@@ -177,6 +187,40 @@ function Shell({ children }: { children: React.ReactNode }) {
  );
 }

+// AccountBar renders the signed-in email + a Sign-out button at the
+// top of the page. Without this the user has no way to log out — the
+// /cp/auth/signout endpoint exists on the control plane but no UI ever
+// called it. Reported externally on 2026-05-05; this is the fix.
+//
+// Click → calls signOut() which POSTs /cp/auth/signout (clears the
+// WorkOS session cookie + revokes at the provider) then bounces to
+// /cp/auth/login. The signOut helper is best-effort — even on a 5xx
+// or network failure the redirect fires so the user never gets stuck
+// on an authed-looking page after they clicked Sign out.
+function AccountBar({ session }: { session: Session }) {
+  const [signingOut, setSigningOut] = useState(false);
+  return (
+    <div className="mb-6 flex items-center justify-between text-sm text-ink-mid">
+      <span title="Signed-in user">{session.email}</span>
+      <button
+        type="button"
+        disabled={signingOut}
+        onClick={async () => {
+          setSigningOut(true);
+          await signOut();
+          // Redirect happens inside signOut; this line is for tests +
+          // edge cases (jsdom, blocked navigation) where it doesn't.
+          setSigningOut(false);
+        }}
+        className="rounded border border-line bg-surface-card px-3 py-1 text-xs text-ink hover:bg-surface-card disabled:opacity-50"
+        aria-label="Sign out"
+      >
+        {signingOut ? "Signing out…" : "Sign out"}
+      </button>
+    </div>
+  );
+}
+
 // DataResidencyNotice surfaces where workspace data lives so EU-based
 // signups can make an informed choice (GDPR Art. 13 disclosure
 // requirement). Plain text, no icon — the goal is clarity, not
@@ -138,14 +138,37 @@ export function A2ATopologyOverlay() {
  // Stable Zustand action reference — safe to call inside effects
  const setA2AEdges = useCanvasStore((s) => s.setA2AEdges);

-  // Read the nodes array as a primitive ref; derive visible IDs outside the selector
-  const nodes = useCanvasStore((s) => s.nodes);
+  // Subscribe to a STABLE STRING KEY of visible workspace IDs, not the
+  // nodes array itself. Zustand returns a new array reference on every
+  // store update (status flips, position drags, peer-discovery writes,
+  // workspace-tab opens, etc.) — even when the set of visible IDs is
+  // unchanged. Selecting a sorted-CSV string makes Zustand's default
+  // shallow-equal short-circuit the re-render unless the actual ID set
+  // changes.
+  //
+  // Why this matters: previously visibleIds was useMemo'd on `nodes`, so
+  // the array reference recreated on every store mutation. fetchAndUpdate
+  // (useCallback'd on visibleIds) then recreated, the useEffect re-fired,
+  // it tore down the 60s setInterval and immediately re-ran the fan-out.
+  // With ~5 store updates/second from heartbeats + polling, the canvas
+  // hammered /workspaces/<id>/activity?type=delegation 5×N requests/sec
+  // until edge rate-limit kicked in with HTTP 429. The recursive React
+  // render trace in the original bug report (uE → ux → uE → ux ...) is
+  // the symptom of this re-render storm.
+  //
+  // The fix is purely the dependency-stability change here; the fetch
+  // logic is unchanged.
+  const visibleIdsKey = useCanvasStore((s) =>
+    s.nodes
+      .filter((n) => !n.hidden)
+      .map((n) => n.id)
+      .sort()
+      .join(",")
+  );

-  // IDs of visible (non-nested, non-hidden) workspace nodes.
-  // Recomputed only when the nodes array reference changes.
  const visibleIds = useMemo(
-    () => nodes.filter((n) => !n.hidden).map((n) => n.id),
-    [nodes]
+    () => (visibleIdsKey ? visibleIdsKey.split(",") : []),
+    [visibleIdsKey]
  );

  // Fetch delegation activity for all visible workspaces and rebuild overlay edges.
@@ -73,14 +73,19 @@ export function ApprovalBanner() {
                <button
                  type="button"
                  onClick={() => handleDecide(approval, "approved")}
-                  className="px-3 py-1.5 bg-emerald-600 hover:bg-emerald-500 text-xs rounded-lg text-white font-medium transition-colors"
+                  // Hover DARKER not lighter — emerald-500 on white text
+                  // drops contrast vs emerald-700.
+                  className="px-3 py-1.5 bg-emerald-600 hover:bg-emerald-700 text-xs rounded-lg text-white font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-amber-950 focus-visible:ring-emerald-400/70"
                >
                  Approve
                </button>
                <button
                  type="button"
                  onClick={() => handleDecide(approval, "denied")}
-                  className="px-3 py-1.5 bg-surface-card hover:bg-surface-card text-xs rounded-lg text-ink-mid transition-colors"
+                  // Was a no-op hover (`bg-surface-card hover:bg-surface-card`).
+                  // Lift to surface-elevated on hover so the button visibly
+                  // responds before a destructive deny.
+                  className="px-3 py-1.5 bg-surface-card hover:bg-surface-elevated hover:text-ink text-xs rounded-lg text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-amber-950 focus-visible:ring-amber-400/70"
                >
                  Deny
                </button>
@@ -30,6 +30,24 @@ export function BatchActionBar() {
    if (count === 0 && hasFailedBatch) setHasFailedBatch(false);
  }, [count, hasFailedBatch]);

+  // Esc clears selection — the deselect button title has been promising
+  // "(Escape)" since the bar shipped, but no handler was wired. Skip when
+  // the confirm dialog is open (`pending !== null`) so the dialog's own
+  // Esc-cancels takes precedence and we don't double-handle the keystroke.
+  // Also skip during a busy in-flight action so the user can't accidentally
+  // strand a partial-failure mid-flight.
+  useEffect(() => {
+    if (count === 0 || pending !== null || busy) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.stopPropagation();
+        clearSelection();
+      }
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [count, pending, busy, clearSelection]);
+
  // Hide when nothing is selected. Hide for single-node selection UNLESS a
  // partial-failure left a survivor awaiting retry.
  if (count === 0) return null;
@@ -129,7 +147,7 @@ export function BatchActionBar() {
        onClick={clearSelection}
        aria-label="Clear selection"
        title="Clear selection (Escape)"
-        className="p-1.5 rounded-lg text-[12px] text-ink-mid hover:text-ink hover:bg-surface-card/50 transition-colors disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-zinc-500/70"
+        className="p-1.5 rounded-lg text-[12px] text-ink-mid hover:text-ink hover:bg-surface-card/50 transition-colors disabled:opacity-50 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent/50"
      >
        ✕
      </button>
@@ -117,9 +117,11 @@ export function BundleDropZone() {
        📦 Import bundle
      </button>

-      {/* Visual overlay when dragging */}
+      {/* Visual overlay when dragging — was hardcoded blue-950/blue-400
+          which doesn't flip with theme. accent colors stay visually
+          consistent with the rest of the canvas in both modes. */}
      {isDragging && (
-        <div className="fixed inset-0 z-20 flex items-center justify-center bg-blue-950/40 backdrop-blur-sm border-2 border-dashed border-blue-400/50 pointer-events-none">
+        <div className="fixed inset-0 z-20 flex items-center justify-center bg-accent/15 backdrop-blur-sm border-2 border-dashed border-accent/40 pointer-events-none">
          <div className="bg-surface-sunken/95 border border-accent/50 rounded-2xl px-8 py-6 shadow-2xl text-center">
            <div className="text-3xl mb-2" aria-hidden="true">📦</div>
            <div className="text-sm font-semibold text-ink">Drop Bundle to Import</div>
@@ -128,10 +130,21 @@ export function BundleDropZone() {
        </div>
      )}

-      {/* Importing spinner */}
+      {/* Importing indicator — role=status + aria-live so SR users hear
+          "Importing bundle..." while the API call is in flight, not just
+          the result toast that fires after. motion-safe:animate-spin
+          respects prefers-reduced-motion (Tailwind's motion-safe variant
+          gates animation on the user's OS setting). */}
      {importing && (
-        <div className="fixed bottom-6 left-1/2 -translate-x-1/2 z-50 bg-surface-sunken/95 border border-line/60 rounded-xl px-5 py-3 shadow-2xl flex items-center gap-3">
-          <div className="w-4 h-4 border-2 border-sky-400 border-t-transparent rounded-full animate-spin" />
+        <div
+          role="status"
+          aria-live="polite"
+          className="fixed bottom-6 left-1/2 -translate-x-1/2 z-50 bg-surface-sunken/95 border border-line/60 rounded-xl px-5 py-3 shadow-2xl flex items-center gap-3"
+        >
+          <div
+            aria-hidden="true"
+            className="w-4 h-4 border-2 border-accent border-t-transparent rounded-full motion-safe:animate-spin"
+          />
          <span className="text-sm text-ink">Importing bundle...</span>
        </div>
      )}
@@ -32,11 +32,18 @@ export function CommunicationOverlay() {

  const fetchComms = useCallback(async () => {
    try {
-      // Fetch activity from all online workspaces
+      // Fan-out cap: each polled workspace = 1 round-trip. The platform
+      // rate limits at 600 req/min/IP; combined with heartbeats + other
+      // canvas polling, every workspace polled here costs ~6 req/min
+      // (1 every 30s × 1 per workspace). Capping at 3 keeps this
+      // overlay's footprint at 18 req/min worst case — well under
+      // budget even with 8+ workspaces visible. Caught 2026-05-04 when
+      // a user with 8+ workspaces (Design Director + 6 sub-agents +
+      // 3 standalones) saw sustained 429s in canvas console.
      const onlineNodes = nodesRef.current.filter((n) => n.data.status === "online");
      const allComms: Communication[] = [];

-      for (const node of onlineNodes.slice(0, 6)) {
+      for (const node of onlineNodes.slice(0, 3)) {
        try {
          const activities = await api.get<Array<{
            id: string;
@@ -91,10 +98,20 @@ export function CommunicationOverlay() {
  }, []);

  useEffect(() => {
+    // Gate polling on visibility — when the user collapses the overlay
+    // the data isn't being read, so the per-workspace fan-out becomes
+    // pure rate-limit overhead. Pre-fix this overlay polled regardless
+    // of whether the panel was shown, costing ~36 req/min from a
+    // hidden surface.
+    if (!visible) return;
    fetchComms();
-    const interval = setInterval(fetchComms, 10000);
+    // 30s cadence (was 10s). At 3-workspace fan-out that's 6 req/min
+    // worst case from this overlay. Combined with heartbeats (~30/min)
+    // and other canvas polling, leaves ample headroom under the 600/
+    // min/IP server-side rate limit even at 8+ workspace tenants.
+    const interval = setInterval(fetchComms, 30000);
    return () => clearInterval(interval);
-  }, [fetchComms]);
+  }, [fetchComms, visible]);

  if (!visible || comms.length === 0) {
    return (
@@ -91,12 +91,15 @@ export function ConfirmDialog({

  if (!open || !mounted) return null;

+  // Hover goes DARKER, not lighter — lighter shades on white text drop
+  // contrast below AA on the accent and red ramps. Darker hovers stay
+  // readable in both light and dark themes.
  const confirmColors =
    confirmVariant === "danger"
-      ? "bg-red-600 hover:bg-red-500 text-white"
+      ? "bg-red-600 hover:bg-red-700 text-white"
      : confirmVariant === "warning"
-        ? "bg-amber-600 hover:bg-amber-500 text-white"
-        : "bg-accent-strong hover:bg-accent text-white";
+        ? "bg-amber-600 hover:bg-amber-700 text-white"
+        : "bg-accent hover:bg-accent-strong text-white";

  // Render via Portal so the fixed-position dialog escapes any containing block
  // (e.g. parents with transform, filter, will-change that break position:fixed).
@@ -123,7 +126,7 @@ export function ConfirmDialog({
            <button
              type="button"
              onClick={onCancel}
-              className="px-3.5 py-1.5 text-[13px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-card border border-line rounded-lg transition-colors"
+              className="px-3.5 py-1.5 text-[13px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-elevated border border-line hover:border-line-soft rounded-lg transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
            >
              Cancel
            </button>
@@ -131,7 +134,7 @@ export function ConfirmDialog({
          <button
            type="button"
            onClick={onConfirm}
-            className={`px-3.5 py-1.5 text-[13px] rounded-lg transition-colors ${confirmColors}`}
+            className={`px-3.5 py-1.5 text-[13px] rounded-lg transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-surface-sunken focus-visible:ring-accent/60 ${confirmColors}`}
          >
            {confirmLabel}
          </button>
@@ -113,7 +113,10 @@ export function ConsoleModal({ workspaceId, workspaceName, open, onClose }: Prop
            ref={closeButtonRef}
            onClick={onClose}
            aria-label="Close"
-            className="text-ink-mid hover:text-ink text-sm px-2"
+            // 24x24 touch target (was ~10x16, well under WCAG 2.5.5).
+            // Hover bg makes the area visible; focus-visible ring matches
+            // the rest of the canvas chrome.
+            className="w-6 h-6 inline-flex items-center justify-center rounded text-sm text-ink-mid hover:text-ink hover:bg-surface-card/40 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 transition-colors"
          >
            ✕
          </button>
@@ -150,12 +153,19 @@ export function ConsoleModal({ workspaceId, workspaceName, open, onClose }: Prop
              type="button"
              onClick={() => {
                if (navigator.clipboard) {
-                  navigator.clipboard.writeText(output);
+                  // Add success feedback — without it, clicking Copy
+                  // looked like a no-op since the previous hover bg was
+                  // also a no-op (`hover:bg-surface-card` on top of the
+                  // same base). Toast confirms the write actually fired.
+                  navigator.clipboard
+                    .writeText(output)
+                    .then(() => showToast("Console output copied", "success"))
+                    .catch(() => showToast("Copy failed", "error"));
                } else {
                  showToast("Copy requires HTTPS — please select and copy manually", "info");
                }
              }}
-              className="px-3 py-1.5 text-[11px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-card border border-line rounded-lg transition-colors"
+              className="px-3 py-1.5 text-[11px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-elevated border border-line hover:border-line-soft rounded-lg transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
            >
              Copy
            </button>
@@ -163,7 +173,10 @@ export function ConsoleModal({ workspaceId, workspaceName, open, onClose }: Prop
          <button
            type="button"
            onClick={onClose}
-            className="px-3 py-1.5 text-[11px] text-ink-mid bg-surface-card hover:bg-surface-card border border-line rounded-lg transition-colors"
+            // Was hover:bg-surface-card (same as base — silent no-op).
+            // Lift to surface-elevated so the button visibly responds,
+            // matching the Cancel button in ConfirmDialog.
+            className="px-3 py-1.5 text-[11px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-elevated border border-line hover:border-line-soft rounded-lg transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
          >
            Close
          </button>
@@ -29,15 +29,38 @@ export function ContextMenu() {
  const setPendingDelete = useCanvasStore((s) => s.setPendingDelete);
  const ref = useRef<HTMLDivElement>(null);
  const [actionLoading, setActionLoading] = useState(false);
+  // Clamped position — (left, top) from contextMenu may overflow when the
+  // user right-clicks near the right/bottom viewport edge. We measure the
+  // rendered menu and shift it back inside on the same frame the cursor
+  // opens it, so it never visibly clips. Falls back to the raw cursor
+  // coords until the rAF runs.
+  const [clamped, setClamped] = useState<{ x: number; y: number } | null>(null);

-  // Auto-focus first enabled item when menu opens
+  // Auto-focus first enabled item when menu opens, AND clamp position.
+  // Both run together in a single rAF so we avoid two synchronous layout
+  // reads + a paint between them.
  useEffect(() => {
    if (!contextMenu) return;
-    requestAnimationFrame(() => {
-      const first = ref.current?.querySelector<HTMLButtonElement>("button:not(:disabled)");
+    setClamped(null);
+    const raf = requestAnimationFrame(() => {
+      const node = ref.current;
+      if (!node) return;
+      const first = node.querySelector<HTMLButtonElement>("button:not(:disabled)");
      first?.focus();
+      // 8px viewport margin so the menu doesn't kiss the edge — matches
+      // the floating-tooltip top-edge clamp in Tooltip.tsx.
+      const margin = 8;
+      const rect = node.getBoundingClientRect();
+      const vw = window.innerWidth;
+      const vh = window.innerHeight;
+      let x = contextMenu.x;
+      let y = contextMenu.y;
+      if (x + rect.width + margin > vw) x = Math.max(margin, vw - rect.width - margin);
+      if (y + rect.height + margin > vh) y = Math.max(margin, vh - rect.height - margin);
+      if (x !== contextMenu.x || y !== contextMenu.y) setClamped({ x, y });
    });
-  }, [contextMenu?.nodeId]);
+    return () => cancelAnimationFrame(raf);
+  }, [contextMenu?.nodeId, contextMenu?.x, contextMenu?.y]);

  // Close on click outside or Escape
  useEffect(() => {
@@ -192,16 +215,6 @@ export function ContextMenu() {
    closeContextMenu();
  }, [contextMenu, selectNode, setPanelTab, closeContextMenu]);

-  const handleExpand = useCallback(async () => {
-    if (!contextMenu) return;
-    try {
-      await api.post(`/workspaces/${contextMenu.nodeId}/expand`, {});
-    } catch (e) {
-      showToast("Expand failed", "error");
-    }
-    closeContextMenu();
-  }, [contextMenu, closeContextMenu]);
-
  const setCollapsed = useCanvasStore((s) => s.setCollapsed);
  const handleCollapse = useCallback(async () => {
    if (!contextMenu) return;
@@ -272,7 +285,7 @@ export function ContextMenu() {
          },
          { label: "Zoom to Team", icon: "⊕", action: handleZoomToTeam },
        ]
-      : [{ label: "Expand to Team", icon: "▷", action: handleExpand }]),
+      : []),
    { label: "", icon: "", action: () => {}, divider: true },
    ...(isPaused
      ? [{ label: "Resume", icon: "▶", action: handleResume }]
@@ -288,7 +301,7 @@ export function ContextMenu() {
      aria-label={`Actions for ${contextMenu.nodeData.name}`}
      onKeyDown={handleMenuKeyDown}
      className="fixed z-[60] min-w-[200px] bg-surface/95 backdrop-blur-xl border border-line/60 rounded-xl shadow-2xl shadow-black/60 py-1 overflow-hidden"
-      style={{ left: contextMenu.x, top: contextMenu.y }}
+      style={{ left: clamped?.x ?? contextMenu.x, top: clamped?.y ?? contextMenu.y }}
    >
      {/* Header */}
      <div className="px-3.5 py-2 border-b border-line/40 mb-0.5">
@@ -314,7 +327,7 @@ export function ContextMenu() {
            onClick={item.action}
            disabled={item.disabled}
            aria-disabled={item.disabled}
-            className={`w-full px-3.5 py-1.5 flex items-center gap-2.5 text-left text-[11px] transition-colors focus:outline-none focus:ring-1 focus:ring-inset focus:ring-zinc-600 disabled:opacity-25 disabled:cursor-not-allowed ${
+            className={`w-full px-3.5 py-1.5 flex items-center gap-2.5 text-left text-[11px] transition-colors focus:outline-none focus-visible:ring-1 focus-visible:ring-inset focus-visible:ring-accent/50 disabled:opacity-25 disabled:cursor-not-allowed ${
              item.danger
                ? "text-bad hover:bg-red-950/40 hover:text-bad"
                : "text-ink-mid hover:bg-surface-card/40 hover:text-ink"
@@ -98,9 +98,17 @@ export function CookieConsent() {
  };

  return (
-    <div
-      role="dialog"
-      aria-modal="true"
+    // role="region" + aria-label, NOT role="dialog" + aria-modal. The
+    // banner is informational — it never blocks the page, never traps
+    // focus, and the user can keep using the canvas while it's up.
+    // Claiming aria-modal="true" without a focus trap is genuinely
+    // harmful for screen-reader users: they get told the rest of the
+    // page is inert, jump into the banner, and then can't escape.
+    // Region semantics let assistive tech navigate around it normally.
+    // (Also: forcing a modal cookie banner would be a dark pattern —
+    // GDPR explicitly discourages it.)
+    <section
+      role="region"
      aria-labelledby="cookie-consent-title"
      aria-describedby="cookie-consent-body"
      className="fixed bottom-0 left-0 right-0 z-[9999] border-t border-line bg-surface/95 backdrop-blur-sm p-4 shadow-[0_-4px_12px_rgba(0,0,0,0.4)]"
@@ -117,7 +125,7 @@ export function CookieConsent() {
            workspaces). See our{" "}
            <a
              href="https://moleculesai.app/legal/privacy"
-              className="text-accent underline hover:text-accent"
+              className="text-accent underline underline-offset-2 hover:text-accent-strong focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 rounded-sm"
              target="_blank"
              rel="noreferrer"
            >
@@ -130,20 +138,20 @@ export function CookieConsent() {
          <button
            type="button"
            onClick={() => decide("rejected")}
-            className="rounded border border-line bg-surface-sunken px-4 py-2 text-sm text-ink hover:bg-surface-card"
+            className="rounded border border-line bg-surface-sunken px-4 py-2 text-sm text-ink hover:bg-surface-card focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
          >
            Necessary only
          </button>
          <button
            type="button"
            onClick={() => decide("accepted")}
-            className="rounded border border-accent bg-accent-strong px-4 py-2 text-sm font-medium text-white hover:bg-accent"
+            className="rounded border border-accent bg-accent-strong px-4 py-2 text-sm font-medium text-white hover:bg-accent focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
          >
            Accept all
          </button>
        </div>
      </div>
-    </div>
+    </section>
  );
 }

@@ -310,7 +310,7 @@ export function CreateWorkspaceButton() {
  return (
    <Dialog.Root open={open} onOpenChange={setOpen}>
      <Dialog.Trigger asChild>
-        <button type="button" className="fixed bottom-6 right-6 z-40 px-5 py-2.5 bg-accent-strong hover:bg-accent active:bg-accent-strong text-sm font-medium rounded-xl text-white shadow-lg shadow-blue-600/20 hover:shadow-xl hover:shadow-blue-500/30 transition-all duration-200 flex items-center gap-2">
+        <button type="button" className="fixed bottom-6 right-6 z-40 px-5 py-2.5 bg-accent hover:bg-accent-strong active:bg-accent text-sm font-medium rounded-xl text-white shadow-lg shadow-accent/20 hover:shadow-xl hover:shadow-accent/30 transition-all duration-200 flex items-center gap-2 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface">
          <svg
            width="14"
            height="14"
@@ -502,7 +502,7 @@ export function CreateWorkspaceButton() {
                  placeholder="sk-…"
                  aria-label="Hermes API key"
                  autoComplete="off"
-                  className="w-full bg-surface-card/60 border border-line/50 rounded-lg px-3 py-2 text-sm text-ink placeholder-zinc-600 focus:outline-none focus:border-violet-500/60 focus:ring-1 focus:ring-violet-500/20 transition-colors font-mono"
+                  className="w-full bg-surface-card/60 border border-line/50 rounded-lg px-3 py-2 text-sm text-ink placeholder-ink-soft focus:outline-none focus:border-violet-500/60 focus:ring-1 focus:ring-violet-500/20 transition-colors font-mono"
                />
              </div>

@@ -527,7 +527,7 @@ export function CreateWorkspaceButton() {
                  autoComplete="off"
                  spellCheck={false}
                  list="hermes-model-suggestions"
-                  className="w-full bg-surface-card/60 border border-line/50 rounded-lg px-3 py-2 text-sm text-ink placeholder-zinc-600 focus:outline-none focus:border-violet-500/60 focus:ring-1 focus:ring-violet-500/20 transition-colors font-mono"
+                  className="w-full bg-surface-card/60 border border-line/50 rounded-lg px-3 py-2 text-sm text-ink placeholder-ink-soft focus:outline-none focus:border-violet-500/60 focus:ring-1 focus:ring-violet-500/20 transition-colors font-mono"
                />
                <datalist id="hermes-model-suggestions">
                  {HERMES_PROVIDERS.find((p) => p.id === hermesProvider)?.models.map(
@@ -552,7 +552,7 @@ export function CreateWorkspaceButton() {

          <div className="flex justify-end gap-2.5 mt-6">
            <Dialog.Close asChild>
-              <button type="button" className="px-4 py-2 bg-surface-card hover:bg-surface-card text-sm rounded-lg text-ink-mid transition-colors">
+              <button type="button" className="px-4 py-2 bg-surface-card hover:bg-surface-elevated hover:text-ink text-sm rounded-lg text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-1 focus-visible:ring-offset-surface">
                Cancel
              </button>
            </Dialog.Close>
@@ -560,7 +560,7 @@ export function CreateWorkspaceButton() {
              type="button"
              onClick={handleCreate}
              disabled={creating}
-              className="px-5 py-2 bg-accent-strong hover:bg-accent active:bg-accent-strong text-sm rounded-lg text-white disabled:opacity-50 transition-colors"
+              className="px-5 py-2 bg-accent hover:bg-accent-strong active:bg-accent text-sm rounded-lg text-white disabled:opacity-50 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-1 focus-visible:ring-offset-surface"
            >
              {creating ? "Creating..." : "Create"}
            </button>
@@ -623,7 +623,7 @@ function InputField({
        placeholder={placeholder}
        min={type === "number" ? "0" : undefined}
        step={type === "number" ? "0.01" : undefined}
-        className={`w-full bg-surface-card/60 border border-line/50 rounded-lg px-3 py-2 text-sm text-ink placeholder-zinc-500 focus:outline-none focus:border-accent/60 focus:ring-1 focus:ring-accent/20 transition-colors ${mono ? "font-mono text-xs" : ""}`}
+        className={`w-full bg-surface-card/60 border border-line/50 rounded-lg px-3 py-2 text-sm text-ink placeholder-ink-soft focus:outline-none focus:border-accent/60 focus:ring-1 focus:ring-accent/20 transition-colors ${mono ? "font-mono text-xs" : ""}`}
      />
      {helper && (
        <p className="mt-1 text-xs text-ink-soft">{helper}</p>
@@ -127,13 +127,16 @@ export function DeleteCascadeConfirmDialog({
            </p>
          </div>

-          {/* Checkbox guard */}
+          {/* Checkbox guard. Ring-offset color was zinc-900 — the dialog
+              actually sits on bg-surface-sunken, so the offset showed
+              the wrong color through the ring gap. Switched to the
+              real bg + a danger-tinted ring. */}
          <label className="flex items-start gap-2.5 cursor-pointer group select-none">
            <input
              type="checkbox"
              checked={checked}
              onChange={(e) => onCheckedChange(e.target.checked)}
-              className="mt-0.5 w-4 h-4 rounded border-line bg-surface-card text-bad focus:ring-red-500 focus:ring-offset-0 focus:ring-offset-zinc-900 cursor-pointer"
+              className="mt-0.5 w-4 h-4 rounded border-line bg-surface-card text-bad cursor-pointer focus:outline-none focus-visible:ring-2 focus-visible:ring-red-500/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface-sunken"
            />
            <span className="text-[12px] text-ink-mid group-hover:text-ink-mid leading-relaxed">
              I understand this will permanently delete all listed workspaces and their data
@@ -145,7 +148,11 @@ export function DeleteCascadeConfirmDialog({
          <button
            type="button"
            onClick={onCancel}
-            className="px-3.5 py-1.5 text-[13px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-card border border-line rounded-lg transition-colors"
+            // Was hover:bg-surface-card (same as base — silent no-op).
+            // Lift to surface-elevated to match the Cancel pattern in
+            // ConfirmDialog. Added focus-visible ring so keyboard users
+            // see where focus lands.
+            className="px-3.5 py-1.5 text-[13px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-elevated border border-line hover:border-line-soft rounded-lg transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-2 focus-visible:ring-offset-surface-sunken"
          >
            Cancel
          </button>
@@ -153,9 +160,12 @@ export function DeleteCascadeConfirmDialog({
            type="button"
            onClick={onConfirm}
            disabled={!checked}
-            className={`px-3.5 py-1.5 text-[13px] rounded-lg transition-colors
+            // Hover goes DARKER, not lighter — bg-red-500 on white text
+            // drops contrast below AA vs bg-red-700. Same trap fixed in
+            // ConfirmDialog and ApprovalBanner. focus-visible ring matches.
+            className={`px-3.5 py-1.5 text-[13px] rounded-lg transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-red-500/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface-sunken
              ${checked
-                ? "bg-red-600 hover:bg-red-500 text-white cursor-pointer"
+                ? "bg-red-600 hover:bg-red-700 text-white cursor-pointer"
                : "bg-red-900/30 text-bad/40 cursor-not-allowed"
              }`}
          >
@@ -48,16 +48,21 @@ export function EmptyState() {
  });

  // "Create blank" bypasses templates entirely — no preflight, no
-  // modal, just POST /workspaces with a default name and tier.
-  // Deliberately NOT routed through useTemplateDeploy because it
-  // has no `template.id` to deploy against.
+  // modal, just POST /workspaces with a default name. Deliberately
+  // NOT routed through useTemplateDeploy because it has no
+  // `template.id` to deploy against.
+  //
+  // tier is omitted so the backend picks a SaaS-aware default
+  // (T4 on SaaS, T3 on self-hosted — see WorkspaceHandler.DefaultTier).
+  // The previous hardcoded `tier: 2` shipped every fresh-tenant agent
+  // at Standard regardless of host, which surprised SaaS users whose
+  // CreateWorkspaceDialog already defaults to T4.
  const createBlank = async () => {
    setBlankCreating(true);
    setBlankError(null);
    try {
      const ws = await api.post<{ id: string }>("/workspaces", {
        name: "My First Agent",
-        tier: 2,
        canvas: firstDeployCoords(),
      });
      handleDeployed(ws.id);
@@ -18,6 +18,8 @@
 import { useCallback, useState } from "react";
 import * as Dialog from "@radix-ui/react-dialog";

+type Tab = "python" | "curl" | "claude" | "mcp" | "hermes" | "codex" | "openclaw" | "fields";
+
 export interface ExternalConnectionInfo {
  workspace_id: string;
  platform_url: string;
@@ -40,6 +42,22 @@ export interface ExternalConnectionInfo {
  // + inbound. Optional for backward compat with platforms that
  // haven't shipped PR #2413 yet.
  universal_mcp_snippet?: string;
+  // Hermes channel snippet — for operators whose external agent IS a
+  // hermes-agent session. Routes A2A traffic into the hermes gateway
+  // via the molecule-channel plugin (Molecule-AI/hermes-channel-molecule).
+  // Long-poll based (no tunnel) — same UX shape as the Claude Code
+  // channel tab. Gives hermes true push parity. Optional for backward
+  // compat with platforms that haven't shipped this PR yet.
+  hermes_channel_snippet?: string;
+  // Codex MCP config snippet — wires the molecule MCP server into
+  // ~/.codex/config.toml so codex agents can call platform tools.
+  // Outbound-tools-only today (codex's MCP client doesn't route
+  // notifications/*); push parity would need a separate bridge daemon.
+  codex_snippet?: string;
+  // OpenClaw MCP config snippet — wires molecule MCP + starts the
+  // openclaw gateway on loopback. Outbound-tools-only today; push
+  // parity on an external openclaw needs a sessions.steer bridge.
+  openclaw_snippet?: string;
 }

 interface Props {
@@ -47,13 +65,19 @@ interface Props {
  onClose: () => void;
 }

-type Tab = "python" | "curl" | "claude" | "mcp" | "fields";
-
 export function ExternalConnectModal({ info, onClose }: Props) {
-  // Default to Claude Code when the platform offers it — that's the
-  // newest + simplest path (no tunnel needed). Falls back to Python
-  // for older platform builds that don't ship the snippet.
-  const initialTab: Tab = info?.claude_code_channel_snippet ? "claude" : "python";
+  // Default to Universal MCP when the platform offers it — runtime-
+  // agnostic outbound tool path that works for any MCP-aware runtime
+  // (Claude Code, hermes, codex, etc.) and lets operators inspect the
+  // primitives before picking a runtime-specific tab. Python SDK is
+  // the fallback for platforms predating the universal_mcp_snippet
+  // field. Pre-2026-05-03 the default was "claude" (Claude Code first)
+  // but operators using non-Claude runtimes opened to a tab they had
+  // to skip past — universal MCP works for everyone as a starting
+  // point and the runtime-specific tabs are still one click away.
+  const initialTab: Tab = info?.universal_mcp_snippet
+    ? "mcp"
+    : "python";
  const [tab, setTab] = useState<Tab>(initialTab);
  const [copiedKey, setCopiedKey] = useState<string | null>(null);

@@ -108,6 +132,24 @@ export function ExternalConnectModal({ info, onClose }: Props) {
    'MOLECULE_WORKSPACE_TOKEN="<paste from create response>"',
    `MOLECULE_WORKSPACE_TOKEN="${info.auth_token}"`,
  );
+  // Hermes channel snippet uses MOLECULE_WORKSPACE_TOKEN (same env-var
+  // name as Universal MCP). Stamp the auth_token in so the operator's
+  // copy-paste is fully ready-to-run.
+  const filledHermes = info.hermes_channel_snippet?.replace(
+    'MOLECULE_WORKSPACE_TOKEN="<paste from create response>"',
+    `MOLECULE_WORKSPACE_TOKEN="${info.auth_token}"`,
+  );
+  // Codex + OpenClaw snippets carry the placeholder inside the
+  // generated config block (TOML / JSON respectively). Stamp the
+  // token in so the copy-paste is one less manual edit.
+  const filledCodex = info.codex_snippet?.replace(
+    'MOLECULE_WORKSPACE_TOKEN = "<paste from create response>"',
+    `MOLECULE_WORKSPACE_TOKEN = "${info.auth_token}"`,
+  );
+  const filledOpenClaw = info.openclaw_snippet?.replace(
+    'WORKSPACE_TOKEN="<paste from create response>"',
+    `WORKSPACE_TOKEN="${info.auth_token}"`,
+  );

  return (
    <Dialog.Root open onOpenChange={(o) => !o && onClose()}>
@@ -135,10 +177,18 @@ export function ExternalConnectModal({ info, onClose }: Props) {
              // 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 (filledChannel) tabs.push("claude");
-              tabs.push("python");
              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");
              tabs.push("curl", "fields");
              return tabs;
            })().map((t) => (
@@ -156,6 +206,12 @@ export function ExternalConnectModal({ info, onClose }: Props) {
              >
                {t === "claude"
                  ? "Claude Code"
+                  : t === "hermes"
+                  ? "Hermes"
+                  : t === "codex"
+                  ? "Codex"
+                  : t === "openclaw"
+                  ? "OpenClaw"
                  : t === "python"
                  ? "Python SDK"
                  : t === "mcp"
@@ -205,6 +261,33 @@ export function ExternalConnectModal({ info, onClose }: Props) {
                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 === "fields" && (
              <div className="space-y-2">
                <Field label="workspace_id" value={info.workspace_id} onCopy={() => copy(info.workspace_id, "wsid")} copied={copiedKey === "wsid"} />
@@ -77,7 +77,7 @@ export function Legend() {
        onClick={openLegend}
        aria-label="Show legend"
        title="Show legend"
-        className={`fixed bottom-6 ${leftClass} z-30 flex items-center gap-1.5 rounded-full bg-surface-sunken/95 border border-line/50 px-3 py-1.5 text-[11px] font-semibold text-ink-mid uppercase tracking-wider shadow-xl shadow-black/30 backdrop-blur-sm hover:text-ink hover:border-line transition-[left,colors] duration-200`}
+        className={`fixed bottom-6 ${leftClass} z-30 flex items-center gap-1.5 rounded-full bg-surface-sunken/95 border border-line/50 px-3 py-1.5 text-[11px] font-semibold text-ink-mid uppercase tracking-wider shadow-xl shadow-black/30 backdrop-blur-sm hover:text-ink hover:border-line focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface transition-[left,colors] duration-200`}
      >
        <span aria-hidden="true" className="text-[10px]">ⓘ</span>
        Legend
@@ -94,7 +94,10 @@ export function Legend() {
          onClick={closeLegend}
          aria-label="Hide legend"
          title="Hide legend"
-          className="-mt-0.5 -mr-1 px-1.5 text-[14px] leading-none text-ink-soft hover:text-ink transition-colors"
+          // 24×24 touch target (was ~10×16, well under WCAG 2.5.5 min).
+          // Negative margin keeps the visual position the same as before
+          // — only the hit area + focus ring are larger.
+          className="-mt-1.5 -mr-1.5 w-6 h-6 inline-flex items-center justify-center rounded text-[14px] leading-none text-ink-soft hover:text-ink hover:bg-surface-card/40 focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 transition-colors"
        >
          ×
        </button>
@@ -0,0 +1,261 @@
+'use client';
+
+import { useEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { api } from "@/lib/api";
+import type { MemoryEntry } from "@/components/MemoryInspectorPanel";
+
+type Scope = "LOCAL" | "TEAM" | "GLOBAL";
+const SCOPES: Scope[] = ["LOCAL", "TEAM", "GLOBAL"];
+
+interface AddProps {
+  open: boolean;
+  mode: "add";
+  workspaceId: string;
+  defaultScope: Scope;
+  defaultNamespace?: string;
+  entry?: undefined;
+  onClose: () => void;
+  onSaved: () => void;
+}
+
+interface EditProps {
+  open: boolean;
+  mode: "edit";
+  workspaceId: string;
+  entry: MemoryEntry;
+  defaultScope?: undefined;
+  defaultNamespace?: undefined;
+  onClose: () => void;
+  onSaved: () => void;
+}
+
+type Props = AddProps | EditProps;
+
+export function MemoryEditorDialog(props: Props) {
+  const { open, mode, workspaceId, onClose, onSaved } = props;
+  const dialogRef = useRef<HTMLDivElement>(null);
+  const [mounted, setMounted] = useState(false);
+  const [scope, setScope] = useState<Scope>("LOCAL");
+  const [namespace, setNamespace] = useState("general");
+  const [content, setContent] = useState("");
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  // Reset form whenever the dialog opens.
+  useEffect(() => {
+    if (!open) return;
+    setError(null);
+    setSaving(false);
+    if (mode === "edit" && props.entry) {
+      setScope(props.entry.scope);
+      setNamespace(props.entry.namespace || "general");
+      setContent(props.entry.content);
+    } else if (mode === "add") {
+      setScope(props.defaultScope);
+      setNamespace(props.defaultNamespace || "general");
+      setContent("");
+    }
+    // mode/props are stable per-open; intentional shallow deps.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [open]);
+
+  // Move focus into the dialog when it opens (WCAG SC 2.4.3).
+  useEffect(() => {
+    if (!open || !mounted) return;
+    const raf = requestAnimationFrame(() => {
+      dialogRef.current?.querySelector<HTMLElement>("textarea, input, select")?.focus();
+    });
+    return () => cancelAnimationFrame(raf);
+  }, [open, mounted]);
+
+  // Escape closes; Cmd/Ctrl-Enter saves.
+  const onCloseRef = useRef(onClose);
+  onCloseRef.current = onClose;
+  const handleSaveRef = useRef<() => void>(() => {});
+  useEffect(() => {
+    if (!open) return;
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.preventDefault();
+        onCloseRef.current();
+      } else if (e.key === "Enter" && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        handleSaveRef.current();
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }, [open]);
+
+  const handleSave = async () => {
+    if (saving) return;
+    const trimmed = content.trim();
+    if (!trimmed) {
+      setError("Content cannot be empty");
+      return;
+    }
+    setError(null);
+    setSaving(true);
+    try {
+      if (mode === "add") {
+        await api.post(`/workspaces/${workspaceId}/memories`, {
+          content: trimmed,
+          scope,
+          namespace: namespace.trim() || "general",
+        });
+      } else {
+        // PATCH only sends fields that changed. Content always changeable;
+        // namespace only sent if it differs from the original (saves a
+        // no-op write through redactSecrets + re-embed).
+        const original = props.entry;
+        const body: Record<string, string> = {};
+        if (trimmed !== original.content) body.content = trimmed;
+        const ns = namespace.trim() || "general";
+        if (ns !== original.namespace) body.namespace = ns;
+        if (Object.keys(body).length === 0) {
+          // No-op edit — close without an HTTP round-trip.
+          onSaved();
+          onClose();
+          return;
+        }
+        await api.patch(
+          `/workspaces/${workspaceId}/memories/${encodeURIComponent(original.id)}`,
+          body,
+        );
+      }
+      onSaved();
+      onClose();
+    } catch (e) {
+      setError(e instanceof Error ? e.message : "Save failed");
+    } finally {
+      setSaving(false);
+    }
+  };
+  handleSaveRef.current = handleSave;
+
+  if (!open || !mounted) return null;
+
+  const titleId = "memory-editor-title";
+  const isEdit = mode === "edit";
+
+  return createPortal(
+    <div className="fixed inset-0 z-[9999] flex items-center justify-center">
+      <div className="absolute inset-0 bg-black/60 backdrop-blur-sm" onClick={onClose} />
+
+      <div
+        ref={dialogRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={titleId}
+        className="relative bg-surface-sunken border border-line rounded-xl shadow-2xl shadow-black/50 max-w-[480px] w-full mx-4 overflow-hidden"
+      >
+        <div className="px-5 py-4 space-y-3">
+          <h3 id={titleId} className="text-sm font-semibold text-ink">
+            {isEdit ? "Edit memory" : "Add memory"}
+          </h3>
+
+          {/* Scope */}
+          <div className="space-y-1">
+            <label className="text-[10px] text-ink-soft block" htmlFor="memory-editor-scope">
+              Scope
+            </label>
+            {isEdit ? (
+              <div
+                id="memory-editor-scope"
+                className="text-[12px] font-mono text-ink-mid bg-surface rounded px-2 py-1.5 border border-line/50"
+                title="Scope is fixed on edit. To move a memory across scopes, delete and re-create it."
+              >
+                {scope}
+              </div>
+            ) : (
+              <div className="flex items-center gap-1" id="memory-editor-scope" role="radiogroup" aria-label="Scope">
+                {SCOPES.map((s) => (
+                  <button
+                    key={s}
+                    type="button"
+                    role="radio"
+                    aria-checked={scope === s}
+                    onClick={() => setScope(s)}
+                    className={[
+                      "px-3 py-1 text-[11px] rounded transition-colors",
+                      scope === s
+                        ? "bg-accent-strong text-white"
+                        : "bg-surface-card text-ink-mid hover:text-ink",
+                    ].join(" ")}
+                  >
+                    {s}
+                  </button>
+                ))}
+              </div>
+            )}
+          </div>
+
+          {/* Namespace */}
+          <div className="space-y-1">
+            <label htmlFor="memory-editor-namespace" className="text-[10px] text-ink-soft block">
+              Namespace
+            </label>
+            <input
+              id="memory-editor-namespace"
+              type="text"
+              value={namespace}
+              onChange={(e) => setNamespace(e.target.value)}
+              placeholder="general"
+              className="w-full bg-surface border border-line/60 focus:border-accent/60 rounded px-2 py-1.5 text-[12px] text-ink placeholder-zinc-600 focus:outline-none transition-colors"
+            />
+          </div>
+
+          {/* Content */}
+          <div className="space-y-1">
+            <label htmlFor="memory-editor-content" className="text-[10px] text-ink-soft block">
+              Content
+            </label>
+            <textarea
+              id="memory-editor-content"
+              value={content}
+              onChange={(e) => setContent(e.target.value)}
+              rows={6}
+              placeholder="What should the agent remember?"
+              className="w-full bg-surface border border-line/60 focus:border-accent/60 rounded px-2 py-1.5 text-[12px] font-mono text-ink placeholder-zinc-600 focus:outline-none transition-colors resize-y min-h-[100px] max-h-[300px]"
+            />
+          </div>
+
+          {error && (
+            <div
+              role="alert"
+              aria-live="assertive"
+              className="px-2 py-1.5 bg-red-950/30 border border-red-800/40 rounded text-[11px] text-bad"
+            >
+              {error}
+            </div>
+          )}
+        </div>
+
+        <div className="flex items-center justify-end gap-2 px-5 py-3 border-t border-line bg-surface/50">
+          <button
+            type="button"
+            onClick={onClose}
+            disabled={saving}
+            className="px-3.5 py-1.5 text-[13px] text-ink-mid hover:text-ink bg-surface-card hover:bg-surface-elevated border border-line hover:border-line-soft rounded-lg transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            Cancel
+          </button>
+          <button
+            type="button"
+            onClick={handleSave}
+            disabled={saving}
+            className="px-3.5 py-1.5 text-[13px] rounded-lg transition-colors bg-accent hover:bg-accent-strong text-white focus:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-surface-sunken focus-visible:ring-accent/60 disabled:opacity-50 disabled:cursor-not-allowed"
+          >
+            {saving ? "Saving…" : isEdit ? "Save changes" : "Add memory"}
+          </button>
+        </div>
+      </div>
+    </div>,
+    document.body,
+  );
+}
@@ -3,6 +3,7 @@
 import { useState, useEffect, useCallback } from "react";
 import { api } from "@/lib/api";
 import { ConfirmDialog } from "@/components/ConfirmDialog";
+import { MemoryEditorDialog } from "@/components/MemoryEditorDialog";

 // ── Types ─────────────────────────────────────────────────────────────────────

@@ -92,6 +93,13 @@ export function MemoryInspectorPanel({ workspaceId }: Props) {
  // ── Delete state ─────────────────────────────────────────────────────────────
  const [pendingDeleteId, setPendingDeleteId] = useState<string | null>(null);

+  // ── Editor state (Add + Edit share one modal) ───────────────────────────────
+  type EditorState =
+    | { mode: "add" }
+    | { mode: "edit"; entry: MemoryEntry }
+    | null;
+  const [editorState, setEditorState] = useState<EditorState>(null);
+
  // ── Data loading ────────────────────────────────────────────────────────────

  const loadEntries = useCallback(async () => {
@@ -241,14 +249,24 @@ export function MemoryInspectorPanel({ workspaceId }: Props) {
            ? "1 memory"
            : `${entries.length} memories`}
        </span>
-        <button
-          type="button"
-          onClick={loadEntries}
-          className="px-2 py-1 text-[11px] bg-surface-card hover:bg-surface-card text-ink-mid rounded transition-colors"
-          aria-label="Refresh memories"
-        >
-          ↻ Refresh
-        </button>
+        <div className="flex items-center gap-1.5">
+          <button
+            type="button"
+            onClick={() => setEditorState({ mode: "add" })}
+            className="px-2 py-1 text-[11px] bg-accent hover:bg-accent-strong text-white rounded transition-colors"
+            aria-label="Add memory"
+          >
+            + Add
+          </button>
+          <button
+            type="button"
+            onClick={loadEntries}
+            className="px-2 py-1 text-[11px] bg-surface-card hover:bg-surface-card text-ink-mid rounded transition-colors"
+            aria-label="Refresh memories"
+          >
+            ↻ Refresh
+          </button>
+        </div>
      </div>

      {/* Error banner */}
@@ -307,6 +325,7 @@ export function MemoryInspectorPanel({ workspaceId }: Props) {
              <MemoryEntryRow
                key={entry.id}
                entry={entry}
+                onEdit={() => setEditorState({ mode: "edit", entry })}
                onDelete={() => setPendingDeleteId(entry.id)}
              />
            ))}
@@ -324,6 +343,29 @@ export function MemoryInspectorPanel({ workspaceId }: Props) {
        onConfirm={confirmDelete}
        onCancel={() => setPendingDeleteId(null)}
      />
+
+      {/* Add / Edit dialog */}
+      {editorState?.mode === "add" && (
+        <MemoryEditorDialog
+          open={true}
+          mode="add"
+          workspaceId={workspaceId}
+          defaultScope={activeScope}
+          defaultNamespace={activeNamespace || "general"}
+          onClose={() => setEditorState(null)}
+          onSaved={loadEntries}
+        />
+      )}
+      {editorState?.mode === "edit" && (
+        <MemoryEditorDialog
+          open={true}
+          mode="edit"
+          workspaceId={workspaceId}
+          entry={editorState.entry}
+          onClose={() => setEditorState(null)}
+          onSaved={loadEntries}
+        />
+      )}
    </div>
  );
 }
@@ -332,10 +374,11 @@ export function MemoryInspectorPanel({ workspaceId }: Props) {

 interface MemoryEntryRowProps {
  entry: MemoryEntry;
+  onEdit: () => void;
  onDelete: () => void;
 }

-function MemoryEntryRow({ entry, onDelete }: MemoryEntryRowProps) {
+function MemoryEntryRow({ entry, onEdit, onDelete }: MemoryEntryRowProps) {
  const [expanded, setExpanded] = useState(false);
  const bodyId = `mem-body-${sanitizeId(entry.id)}`;

@@ -413,17 +456,30 @@ function MemoryEntryRow({ entry, onDelete }: MemoryEntryRowProps) {
            <span className="text-[9px] text-ink-soft">
              Created: {new Date(entry.created_at).toLocaleString()}
            </span>
-            <button
-              type="button"
-              onClick={(e) => {
-                e.stopPropagation();
-                onDelete();
-              }}
-              aria-label="Delete memory"
-              className="text-[10px] px-2 py-0.5 bg-red-950/40 hover:bg-red-900/50 border border-red-900/30 rounded text-bad transition-colors shrink-0"
-            >
-              Delete
-            </button>
+            <div className="flex items-center gap-1.5 shrink-0">
+              <button
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onEdit();
+                }}
+                aria-label="Edit memory"
+                className="text-[10px] px-2 py-0.5 bg-surface-card hover:bg-surface-elevated border border-line/40 rounded text-ink-mid hover:text-ink transition-colors"
+              >
+                Edit
+              </button>
+              <button
+                type="button"
+                onClick={(e) => {
+                  e.stopPropagation();
+                  onDelete();
+                }}
+                aria-label="Delete memory"
+                className="text-[10px] px-2 py-0.5 bg-red-950/40 hover:bg-red-900/50 border border-red-900/30 rounded text-bad transition-colors"
+              >
+                Delete
+              </button>
+            </div>
          </div>
        </div>
      )}
@@ -134,10 +134,12 @@ export function OnboardingWizard() {
      aria-label="Onboarding guide"
      className="fixed bottom-20 left-4 z-50 w-80 rounded-2xl border border-line/60 bg-surface-sunken/95 backdrop-blur-xl shadow-2xl shadow-black/40 overflow-hidden"
    >
-      {/* Progress bar */}
+      {/* Progress bar — was hardcoded from-blue-500 to-sky-400, neither
+          tone exists in warm-paper light theme. Switched to the accent
+          ramp so the gradient reads as brand color in both themes. */}
      <div className="h-1 bg-surface-card">
        <div
-          className="h-full bg-gradient-to-r from-blue-500 to-sky-400 transition-all duration-500"
+          className="h-full bg-gradient-to-r from-accent to-accent-strong transition-all duration-500"
          style={{ width: `${((currentStepIdx + 1) / STEPS.length) * 100}%` }}
        />
      </div>
@@ -155,14 +157,16 @@ export function OnboardingWizard() {
      <div className="p-4">
        {/* Step indicator */}
        <div className="flex items-center justify-between mb-2">
-          <span className="text-[9px] font-semibold uppercase tracking-widest text-sky-400/80">
+          {/* text-sky-400/80 was hardcoded; flip to text-accent so the
+              indicator stays brand-tinted in both themes. */}
+          <span className="text-[9px] font-semibold uppercase tracking-widest text-accent">
            Step {currentStepIdx + 1} of {STEPS.length}
          </span>
          <button
            type="button"
            onClick={dismiss}
            aria-label="Skip onboarding guide"
-            className="text-[10px] text-ink-mid hover:text-ink transition-colors"
+            className="text-[10px] text-ink-mid hover:text-ink transition-colors rounded-sm focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/50"
          >
            Skip guide
          </button>
@@ -181,7 +185,11 @@ export function OnboardingWizard() {
          <button
            type="button"
            onClick={handleAction}
-            className="flex-1 px-3 py-1.5 bg-accent-strong/90 hover:bg-accent rounded-lg text-[11px] font-medium text-white transition-colors"
+            // Was bg-accent-strong/90 hover:bg-accent — accent is the
+            // LIGHTER variant, so this hovered lighter on white text and
+            // dropped contrast below AA. Same trap fixed in
+            // ConfirmDialog/ApprovalBanner. Hover the OTHER direction.
+            className="flex-1 px-3 py-1.5 bg-accent hover:bg-accent-strong rounded-lg text-[11px] font-medium text-white transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface-sunken"
          >
            {step === "welcome"
              ? "Create Workspace"
@@ -199,7 +207,10 @@ export function OnboardingWizard() {
                if (next) setStep(next.id);
                else dismiss();
              }}
-              className="px-3 py-1.5 bg-surface-card hover:bg-surface-card rounded-lg text-[11px] text-ink-mid transition-colors"
+              // Was hover:bg-surface-card on top of bg-surface-card —
+              // silent no-op hover. Lift to surface-elevated, matching
+              // the Cancel pattern in ConfirmDialog.
+              className="px-3 py-1.5 bg-surface-card hover:bg-surface-elevated hover:text-ink rounded-lg text-[11px] text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-2 focus-visible:ring-offset-surface-sunken"
            >
              Next
            </button>
@@ -293,7 +293,7 @@ export function OrgImportPreflightModal({
          <button
            type="button"
            onClick={onCancel}
-            className="px-3 py-1.5 text-[11px] rounded bg-surface-card hover:bg-surface-card text-ink-mid"
+            className="px-3 py-1.5 text-[11px] rounded bg-surface-card hover:bg-surface-elevated hover:text-ink text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-1 focus-visible:ring-offset-surface"
          >
            Cancel
          </button>
@@ -308,7 +308,7 @@ export function OrgImportPreflightModal({
              type="button"
              onClick={onProceed}
              disabled={!canProceed}
-              className="px-4 py-1.5 text-[11px] font-semibold rounded bg-accent-strong hover:bg-accent text-white disabled:bg-surface-card disabled:text-white-soft disabled:cursor-not-allowed"
+              className="px-4 py-1.5 text-[11px] font-semibold rounded bg-accent hover:bg-accent-strong text-white disabled:bg-surface-card disabled:text-white-soft disabled:cursor-not-allowed"
            >
              Import
            </button>
@@ -428,7 +428,7 @@ function StrictEnvRow({
            type="button"
            onClick={() => onSave(envKey)}
            disabled={d?.saving || !d?.value.trim()}
-            className="px-2 py-1 text-[10px] rounded bg-accent-strong hover:bg-accent text-white disabled:opacity-40 disabled:cursor-not-allowed"
+            className="px-2 py-1 text-[10px] rounded bg-accent hover:bg-accent-strong text-white disabled:opacity-40 disabled:cursor-not-allowed"
          >
            {d?.saving ? "…" : "Save"}
          </button>
@@ -520,7 +520,7 @@ function AnyOfEnvGroup({
                    type="button"
                    onClick={() => onSave(m)}
                    disabled={d?.saving || !d?.value.trim()}
-                    className="px-2 py-1 text-[10px] rounded bg-accent-strong hover:bg-accent text-white disabled:opacity-40 disabled:cursor-not-allowed"
+                    className="px-2 py-1 text-[10px] rounded bg-accent hover:bg-accent-strong text-white disabled:opacity-40 disabled:cursor-not-allowed"
                  >
                    {d?.saving ? "…" : "Save"}
                  </button>
@@ -36,11 +36,6 @@ export function SearchDialog() {
    }
  }, [open]);

-  // Reset focused index when query changes
-  useEffect(() => {
-    setFocusedIndex(-1);
-  }, [query]);
-
  const filtered = nodes.filter((n) => {
    if (!query) return true;
    const q = query.toLowerCase();
@@ -51,6 +46,18 @@ export function SearchDialog() {
    );
  });

+  // Auto-highlight the first match while the user is typing, so Enter
+  // selects something instead of being a no-op. With an empty query we
+  // keep -1 so opening the dialog (which shows ALL workspaces) doesn't
+  // visually pin one row arbitrarily — only commit a highlight once the
+  // user has narrowed the list.
+  useEffect(() => {
+    setFocusedIndex(query && filtered.length > 0 ? 0 : -1);
+    // Re-running on filtered.length keeps the highlight pinned to the
+    // first row while the result set shrinks/grows; the effect handler
+    // above already short-circuits to -1 when results disappear.
+  }, [query, filtered.length]);
+
  const handleSelect = useCallback(
    (nodeId: string) => {
      selectNode(nodeId);
@@ -113,7 +120,7 @@ export function SearchDialog() {
            onChange={(e) => setQuery(e.target.value)}
            onKeyDown={handleInputKeyDown}
            placeholder="Search workspaces..."
-            className="flex-1 bg-transparent text-sm text-ink placeholder-zinc-400 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent focus:outline-none rounded"
+            className="flex-1 bg-transparent text-sm text-ink placeholder-ink-soft focus:outline-none focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-accent rounded"
          />
          <kbd className="text-[9px] text-ink-mid bg-surface-card/60 px-1.5 py-0.5 rounded border border-line/40">ESC</kbd>
        </div>
@@ -283,7 +283,7 @@ export function SidePanel() {
        {panelTab === "skills" && <SkillsTab key={selectedNodeId} workspaceId={selectedNodeId} data={node.data} />}
        {panelTab === "activity" && <ActivityTab key={selectedNodeId} workspaceId={selectedNodeId} />}
        {panelTab === "chat" && <ChatTab key={selectedNodeId} workspaceId={selectedNodeId} data={node.data} />}
-        {panelTab === "terminal" && <TerminalTab key={selectedNodeId} workspaceId={selectedNodeId} />}
+        {panelTab === "terminal" && <TerminalTab key={selectedNodeId} workspaceId={selectedNodeId} data={node.data} />}
        {panelTab === "config" && <ConfigTab key={selectedNodeId} workspaceId={selectedNodeId} />}
        {panelTab === "schedule" && <ScheduleTab key={selectedNodeId} workspaceId={selectedNodeId} />}
        {panelTab === "channels" && <ChannelsTab key={selectedNodeId} workspaceId={selectedNodeId} />}
@@ -1,6 +1,6 @@
 "use client";

-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import { PLATFORM_URL } from "@/lib/api";

 // TermsGate blocks the page it wraps until the user has accepted the
@@ -73,39 +73,72 @@ export function TermsGate({ children }: { children: React.ReactNode }) {
    }
  };

+  // Move focus to the "I agree" button when the modal opens (WCAG 2.4.3).
+  // The dialog is a hard gate — no Esc dismiss — so we don't need a focus
+  // trap loop, just a one-shot focus move into the dialog.
+  const agreeButtonRef = useRef<HTMLButtonElement>(null);
+  useEffect(() => {
+    if (status !== "pending") return;
+    const raf = requestAnimationFrame(() => agreeButtonRef.current?.focus());
+    return () => cancelAnimationFrame(raf);
+  }, [status]);
+
  return (
    <>
      {children}
      {status === "pending" && (
-        <div aria-hidden="true" className="fixed inset-0 z-50 flex items-center justify-center bg-surface/80 backdrop-blur-sm">
+        // Backdrop is decorative — does NOT carry aria-hidden anymore.
+        // The earlier version put aria-hidden="true" on this wrapper,
+        // which hid the dialog AND its descendants from screen readers,
+        // making the entire terms-acceptance flow invisible to AT users.
+        // Backdrop click intentionally does nothing — this is a hard
+        // gate.
+        <div className="fixed inset-0 z-50 flex items-center justify-center bg-surface/80 backdrop-blur-sm">
          <div
            role="dialog"
            aria-modal="true"
            aria-labelledby="terms-dialog-title"
+            aria-describedby="terms-dialog-body"
            className="mx-4 max-w-lg rounded-lg border border-line bg-surface-sunken p-6 shadow-xl"
          >
            <h2 id="terms-dialog-title" className="text-lg font-semibold text-ink">Terms &amp; conditions</h2>
-            <p className="mt-3 text-sm text-ink-mid">
-              Before you create an organization, please review our{" "}
-              <a href="/legal/terms" className="text-sky-400 underline" target="_blank" rel="noreferrer">
-                Terms of Service
-              </a>{" "}
-              and{" "}
-              <a href="/legal/privacy" className="text-sky-400 underline" target="_blank" rel="noreferrer">
-                Privacy Policy
-              </a>
-              . Click agree to continue.
-            </p>
-            <p className="mt-3 text-xs text-ink-soft">
-              By agreeing you acknowledge that workspace data is stored in AWS us-east-2 (Ohio, United States).
-            </p>
+            <div id="terms-dialog-body">
+              <p className="mt-3 text-sm text-ink-mid">
+                Before you create an organization, please review our{" "}
+                <a
+                  href="/legal/terms"
+                  className="text-accent underline underline-offset-2 hover:text-accent-strong focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 rounded-sm"
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  Terms of Service
+                </a>{" "}
+                and{" "}
+                <a
+                  href="/legal/privacy"
+                  className="text-accent underline underline-offset-2 hover:text-accent-strong focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 rounded-sm"
+                  target="_blank"
+                  rel="noreferrer"
+                >
+                  Privacy Policy
+                </a>
+                . Click agree to continue.
+              </p>
+              <p className="mt-3 text-xs text-ink-soft">
+                By agreeing you acknowledge that workspace data is stored in AWS us-east-2 (Ohio, United States).
+              </p>
+            </div>
            {error && <p role="alert" className="mt-3 text-sm text-bad">{error}</p>}
            <div className="mt-5 flex justify-end gap-2">
              <button
                type="button"
+                ref={agreeButtonRef}
                onClick={accept}
                disabled={submitting}
-                className="rounded bg-emerald-600 px-4 py-2 text-sm font-medium text-white hover:bg-emerald-500 disabled:opacity-50"
+                // Hover goes DARKER, not lighter — emerald-500 on white
+                // text drops contrast below AA vs emerald-700. Same trap
+                // I fixed in ApprovalBanner + ConfirmDialog.
+                className="rounded bg-emerald-600 hover:bg-emerald-700 px-4 py-2 text-sm font-medium text-white disabled:opacity-50 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-emerald-400/70 focus-visible:ring-offset-2 focus-visible:ring-offset-surface-sunken"
              >
                {submitting ? "Saving…" : "I agree"}
              </button>
@@ -38,6 +38,18 @@ export function Toaster() {
    };
  }, []);

+  // Esc dismisses the newest toast — keyboard parity with the × button.
+  // Errors never auto-expire, so without this a keyboard-only user has to
+  // tab through the entire app to reach the dismiss button on a stuck error.
+  useEffect(() => {
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== "Escape") return;
+      setToasts((prev) => (prev.length === 0 ? prev : prev.slice(0, -1)));
+    };
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, []);
+
  const toastCls = (type: Toast["type"]) =>
    `flex items-center gap-2 pl-4 pr-2 py-2.5 rounded-xl shadow-2xl shadow-black/40 text-sm backdrop-blur-md animate-in slide-in-from-bottom duration-200 ${
      type === "success"
@@ -47,6 +59,17 @@ export function Toaster() {
        : "bg-surface-sunken/90 border border-line/40 text-ink"
    }`;

+  // Success/error toasts are intentionally dark in both themes (high-vis).
+  // Info uses the semantic surface that flips with theme — so the dismiss
+  // button needs a tint that stays visible on a light bg in light mode.
+  const dismissCls = (type: Toast["type"]) => {
+    const base =
+      "ml-1 w-7 h-7 inline-flex items-center justify-center text-base leading-none rounded transition-colors opacity-70 hover:opacity-100 focus-visible:opacity-100 focus:outline-none focus-visible:ring-2 shrink-0";
+    return type === "info"
+      ? `${base} hover:bg-ink/10 focus-visible:ring-accent/60`
+      : `${base} hover:bg-white/15 focus-visible:ring-white/70`;
+  };
+
  const pos =
    "fixed bottom-16 left-1/2 -translate-x-1/2 z-[80] flex flex-col gap-2 items-center";

@@ -66,7 +89,7 @@ export function Toaster() {
                type="button"
                onClick={() => dismiss(toast.id)}
                aria-label="Dismiss notification"
-                className="ml-1 p-1 rounded hover:bg-surface-card/50 transition-colors opacity-70 hover:opacity-100 shrink-0"
+                className={dismissCls(toast.type)}
              >
                ×
              </button>
@@ -94,7 +117,7 @@ export function Toaster() {
                type="button"
                onClick={() => dismiss(toast.id)}
                aria-label="Dismiss notification"
-                className="ml-1 p-1 rounded hover:bg-surface-card/50 transition-colors opacity-70 hover:opacity-100 shrink-0"
+                className={dismissCls(toast.type)}
              >
                ×
              </button>
@@ -154,10 +154,10 @@ export function Toolbar() {
        {counts.failed > 0 && (
          <StatusPill color={statusDotClass("failed")} count={counts.failed} label="failed" />
        )}
-        <span className="text-ink-soft" aria-hidden="true">·</span>
-        <span className="text-[10px] text-ink-soft whitespace-nowrap">
+        <span className="text-ink-mid" aria-hidden="true">·</span>
+        <span className="text-[10px] text-ink-mid whitespace-nowrap">
          {counts.roots} workspace{counts.roots !== 1 ? "s" : ""}
-          {counts.children > 0 && <span className="text-ink-soft"> + {counts.children} sub</span>}
+          {counts.children > 0 && <span className="text-ink-mid"> + {counts.children} sub</span>}
        </span>
      </div>

@@ -172,7 +172,7 @@ export function Toolbar() {
          type="button"
          onClick={stopAll}
          disabled={stopping}
-          className="flex items-center gap-1.5 px-2.5 py-1 bg-red-950/50 hover:bg-red-900/60 border border-red-800/40 rounded-lg transition-colors disabled:opacity-50"
+          className="flex items-center gap-1.5 px-2.5 py-1 bg-bad/10 hover:bg-bad/20 border border-bad/40 rounded-lg transition-colors disabled:opacity-50 focus:outline-none focus-visible:ring-2 focus-visible:ring-bad/40"
          title={`Stop all running tasks (${counts.activeTasks} active)`}
          aria-label={stopping ? "Stopping all running tasks" : `Stop all running tasks (${counts.activeTasks} active)`}
        >
@@ -191,7 +191,7 @@ export function Toolbar() {
          type="button"
          onClick={() => setRestartConfirmOpen(true)}
          disabled={restartingAll}
-          className="flex items-center gap-1.5 px-2.5 py-1 bg-amber-950/40 hover:bg-amber-900/50 border border-amber-800/40 rounded-lg transition-colors disabled:opacity-50"
+          className="flex items-center gap-1.5 px-2.5 py-1 bg-warm/10 hover:bg-warm/20 border border-warm/40 rounded-lg transition-colors disabled:opacity-50 focus:outline-none focus-visible:ring-2 focus-visible:ring-warm/40"
          title={`Restart ${needsRestartNodes.length} workspace${needsRestartNodes.length === 1 ? "" : "s"} that need to pick up config or secret changes`}
          aria-label={restartingAll ? "Restarting workspaces" : `Restart ${needsRestartNodes.length} workspace${needsRestartNodes.length === 1 ? "" : "s"} pending config or secret changes`}
        >
@@ -216,10 +216,10 @@ export function Toolbar() {
        aria-pressed={showA2AEdges}
        aria-label={showA2AEdges ? "Hide A2A edges" : "Show A2A edges"}
        title={showA2AEdges ? "Hide A2A delegation edges" : "Show A2A delegation edges (last 60 min)"}
-        className={`flex items-center justify-center w-7 h-7 border rounded-lg transition-colors ${
+        className={`flex items-center justify-center w-7 h-7 border rounded-lg transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${
          showA2AEdges
-            ? "bg-blue-950/50 hover:bg-blue-900/50 border-blue-800/40 text-accent"
-            : "bg-surface-card/50 hover:bg-surface-card/50 border-line/40 text-ink-soft hover:text-ink-mid"
+            ? "bg-accent/15 hover:bg-accent/25 border-accent/50 text-accent"
+            : "bg-surface-card hover:bg-surface-card/70 border-line text-ink-mid hover:text-ink"
        }`}
      >
        {/* Mesh / network icon */}
@@ -255,7 +255,7 @@ export function Toolbar() {
        }}
        aria-label="Open audit trail for selected workspace"
        title="Audit — view ledger for the selected workspace"
-        className="flex items-center justify-center w-7 h-7 bg-surface-card/50 hover:bg-surface-card/50 border border-line/40 rounded-lg transition-colors text-ink-soft hover:text-ink-mid"
+        className="flex items-center justify-center w-7 h-7 bg-surface-card hover:bg-surface-card/70 border border-line rounded-lg transition-colors text-ink-mid hover:text-ink focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
      >
        {/* Scroll / ledger icon */}
        <svg
@@ -277,7 +277,7 @@ export function Toolbar() {
        onClick={() => useCanvasStore.getState().setSearchOpen(true)}
        aria-label="Search workspaces"
        title="Search (⌘K)"
-        className="flex items-center justify-center w-7 h-7 bg-surface-card/50 hover:bg-surface-card/50 border border-line/40 rounded-lg transition-colors text-ink-soft hover:text-ink-mid"
+        className="flex items-center justify-center w-7 h-7 bg-surface-card hover:bg-surface-card/70 border border-line rounded-lg transition-colors text-ink-mid hover:text-ink focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
      >
        <svg width="14" height="14" viewBox="0 0 16 16" fill="none" aria-hidden="true">
          <circle cx="7" cy="7" r="5" stroke="currentColor" strokeWidth="1.5" />
@@ -290,7 +290,7 @@ export function Toolbar() {
        <button
          type="button"
          onClick={() => setHelpOpen((open) => !open)}
-          className="flex items-center justify-center w-7 h-7 bg-surface-card/50 hover:bg-surface-card/50 border border-line/40 rounded-lg transition-colors text-ink-soft hover:text-ink-mid"
+          className="flex items-center justify-center w-7 h-7 bg-surface-card hover:bg-surface-card/70 border border-line rounded-lg transition-colors text-ink-mid hover:text-ink focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40"
          aria-expanded={helpOpen}
          aria-label="Open quick help"
          title="Help — shortcuts & quick start"
@@ -308,7 +308,7 @@ export function Toolbar() {
              <button
                type="button"
                onClick={() => setHelpOpen(false)}
-                className="text-[10px] text-ink-soft hover:text-ink-mid transition-colors"
+                className="text-[10px] text-ink-mid hover:text-ink transition-colors focus:outline-none focus-visible:underline"
              >
                Close
              </button>
@@ -316,7 +316,7 @@ export function Toolbar() {
            <div className="space-y-2">
              <HelpRow shortcut="⌘K" text="Search workspaces and jump straight into Details or Chat." />
              <HelpRow shortcut="Palette" text="Open the template palette to deploy a new workspace." />
-              <HelpRow shortcut="Right-click" text="Use node actions for expand, duplicate, export, restart, or delete." />
+              <HelpRow shortcut="Right-click" text="Use node actions for duplicate, export, restart, or delete." />
              <HelpRow shortcut="Chat" text="If a task is still running, the chat tab resumes that session automatically." />
              <HelpRow shortcut="Config" text="Use the Config tab for skills, model, secrets, and runtime settings." />
              <HelpRow shortcut="Dbl-click / Z" text="Zoom canvas to fit a team node and all its sub-workspaces." />
@@ -358,7 +358,7 @@ function WsStatusPill({ status }: { status: "connected" | "connecting" | "discon
    return (
      <div className="flex items-center gap-1.5" title="Real-time updates: connected" aria-label="Real-time updates: connected">
        <div className={`w-1.5 h-1.5 rounded-full ${statusDotClass("online")}`} aria-hidden="true" />
-        <span className="text-[10px] text-ink-soft" aria-hidden="true">Live</span>
+        <span className="text-[10px] text-ink-mid" aria-hidden="true">Live</span>
      </div>
    );
  }
@@ -366,14 +366,14 @@ function WsStatusPill({ status }: { status: "connected" | "connecting" | "discon
    return (
      <div className="flex items-center gap-1.5" title="Real-time updates: reconnecting…" aria-label="Real-time updates: reconnecting">
        <div className="w-1.5 h-1.5 rounded-full bg-amber-400 motion-safe:animate-pulse" aria-hidden="true" />
-        <span className="text-[10px] text-ink-soft" aria-hidden="true">Reconnecting</span>
+        <span className="text-[10px] text-warm" aria-hidden="true">Reconnecting</span>
      </div>
    );
  }
  return (
    <div className="flex items-center gap-1.5" title="Real-time updates: disconnected" aria-label="Real-time updates: disconnected">
      <div className={`w-1.5 h-1.5 rounded-full ${statusDotClass("failed")}`} aria-hidden="true" />
-      <span className="text-[10px] text-ink-soft" aria-hidden="true">Offline</span>
+      <span className="text-[10px] text-bad" aria-hidden="true">Offline</span>
    </div>
  );
 }
@@ -384,7 +384,7 @@ function HelpRow({ shortcut, text }: { shortcut: string; text: string }) {
      <span className="shrink-0 rounded-md border border-line/60 bg-surface/70 px-2 py-0.5 text-[9px] font-medium uppercase tracking-[0.18em] text-ink-mid">
        {shortcut}
      </span>
-      <p className="text-[11px] leading-relaxed text-ink-soft">{text}</p>
+      <p className="text-[11px] leading-relaxed text-ink-mid">{text}</p>
    </div>
  );
 }
@@ -22,6 +22,24 @@ export function Tooltip({ text, children }: Props) {

  useEffect(() => () => clearTimeout(timerRef.current), []);

+  // WCAG 1.4.13 (Content on Hover or Focus) — Dismissible: a mechanism
+  // is available to dismiss the additional content WITHOUT moving
+  // pointer hover or keyboard focus. Esc dismisses while the trigger
+  // stays focused/hovered, so a screen-magnifier user can read what
+  // the tooltip was covering without losing their place.
+  useEffect(() => {
+    if (!show) return;
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === "Escape") {
+        e.stopPropagation();
+        clearTimeout(timerRef.current);
+        setShow(false);
+      }
+    };
+    window.addEventListener("keydown", onKey, true);
+    return () => window.removeEventListener("keydown", onKey, true);
+  }, [show]);
+
  const enter = useCallback(() => {
    timerRef.current = setTimeout(() => {
      if (triggerRef.current) {
@@ -3,6 +3,7 @@
 import { useCallback, useMemo } from "react";
 import { Handle, NodeResizer, Position, type NodeProps, type Node } from "@xyflow/react";
 import { useCanvasStore, type WorkspaceNodeData } from "@/store/canvas";
+import { getConfigurationError, getConfigurationStatus } from "@/store/canvas-topology";
 import { showToast } from "@/components/Toaster";
 import { Tooltip } from "@/components/Tooltip";
 import { STATUS_CONFIG, TIER_CONFIG } from "@/lib/design-tokens";
@@ -35,8 +36,28 @@ function EjectIcon(props: React.SVGProps<SVGSVGElement>) {
 }

 export function WorkspaceNode({ id, data }: NodeProps<Node<WorkspaceNodeData>>) {
-  const statusCfg = STATUS_CONFIG[data.status] || STATUS_CONFIG.offline;
+  // Configuration-status overlay (PR #2756 / #467 chain). When the
+  // workspace is reachable but adapter.setup() failed (typically a
+  // missing/rotated LLM credential), the agent_card carries
+  // configuration_status: "not_configured". Surface this as a distinct
+  // tile state so the operator sees a useful error instead of an
+  // ambiguous "online but silent" workspace.
+  //
+  // The override only applies when the underlying status is "online" —
+  // a workspace that's actually offline / failed / provisioning gets
+  // its own treatment. "online + not_configured" is the gap PR #2756
+  // introduced; everything else was already covered.
+  const isMisconfigured =
+    data.status === "online" &&
+    getConfigurationStatus(data.agentCard) === "not_configured";
+  const configurationError = getConfigurationError(data.agentCard);
+  const effectiveStatus = isMisconfigured ? "not_configured" : data.status;
+  const statusCfg = STATUS_CONFIG[effectiveStatus] || STATUS_CONFIG.offline;
  const tierCfg = TIER_CONFIG[data.tier] || { label: `T${data.tier}`, color: "text-ink-mid bg-surface-card border border-line" };
+  const tooltipExtra = isMisconfigured && configurationError
+    ? `Agent not configured: ${configurationError}`
+    : null;
+  void tooltipExtra; // wired in via aria-label below; reserved here for future tooltip surface.
  // Org-deploy context — four derived flags off one store subscription.
  // Drives the shimmer while provisioning, the dimmed/non-draggable
  // treatment on locked descendants, and the Cancel pill on the root.
@@ -75,7 +96,12 @@ export function WorkspaceNode({ id, data }: NodeProps<Node<WorkspaceNodeData>>)
    <div
      role="button"
      tabIndex={0}
-      aria-label={`${data.name} workspace — ${data.status}`}
+      aria-label={
+        isMisconfigured && configurationError
+          ? `${data.name} workspace — agent not configured: ${configurationError}`
+          : `${data.name} workspace — ${data.status}`
+      }
+      title={isMisconfigured && configurationError ? `Agent not configured: ${configurationError}` : undefined}
      aria-pressed={isSelected}
      onClick={(e) => {
        e.stopPropagation();
@@ -283,11 +309,12 @@ export function WorkspaceNode({ id, data }: NodeProps<Node<WorkspaceNodeData>>)

        {/* Bottom row: status / active tasks */}
        <div className="flex items-center justify-between mt-0.5">
-          {data.status !== "online" ? (
+          {effectiveStatus !== "online" ? (
            <div className={`text-[10px] uppercase tracking-widest font-medium ${
-              data.status === "failed" ? "text-bad" :
-              data.status === "degraded" ? "text-warm" :
-              data.status === "provisioning" ? "text-accent" :
+              effectiveStatus === "failed" ? "text-bad" :
+              effectiveStatus === "degraded" ? "text-warm" :
+              effectiveStatus === "not_configured" ? "text-warm" :
+              effectiveStatus === "provisioning" ? "text-accent" :
              "text-ink-mid"
            }`}>
              {statusCfg.label}
@@ -313,6 +340,19 @@ export function WorkspaceNode({ id, data }: NodeProps<Node<WorkspaceNodeData>>)
            {data.lastSampleError}
          </div>
        )}
+
+        {/* Configuration error preview — same visual as the degraded
+         *  error preview but keyed off the agent_card's configuration_status.
+         *  Tells the operator which env var is missing so they can fix it
+         *  without having to dig into the workspace logs. */}
+        {isMisconfigured && configurationError && (
+          <div
+            className="text-[10px] text-warm truncate mt-1 bg-warm/10 px-1.5 py-0.5 rounded border border-warm/40"
+            title={configurationError}
+          >
+            {configurationError}
+          </div>
+        )}
      </div>

      <Handle
@@ -296,4 +296,75 @@ describe("A2ATopologyOverlay component", () => {
    // setA2AEdges should still be called with an empty array
    expect(mockStoreState.setA2AEdges).toHaveBeenCalled();
  });
+
+  // Regression for the 2026-05-04 render-loop incident:
+  // tenant heartbeats / status flips / peer-discovery writes mutated
+  // canvas store .nodes ~5x/sec. Previously visibleIds was useMemo'd on
+  // [nodes] so the array reference recreated on every store mutation,
+  // causing fetchAndUpdate to recreate, the useEffect to re-fire, and
+  // the 60-second polling fan-out to fire on EVERY store update. With
+  // 5 visible workspaces and 5 store updates/sec, the canvas hammered
+  // /workspaces/<id>/activity?type=delegation 25×/sec until edge rate
+  // -limit returned 429 (per browser console captured by user).
+  //
+  // Fix: select a stable string key (sorted CSV of IDs) from Zustand
+  // so the selector's shallow-equal short-circuit prevents re-renders
+  // when the actual ID set hasn't changed.
+  //
+  // This test verifies the fetch fires ONCE on mount + only re-fires
+  // when the visible ID set actually changes, NOT on every nodes[]
+  // reference change.
+  it("does not re-fetch when nodes[] reference changes but visible IDs are the same", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mockGet.mockResolvedValue([] as any);
+    const { rerender } = render(<A2ATopologyOverlay />);
+    await act(async () => { await Promise.resolve(); await Promise.resolve(); });
+
+    const callsAfterMount = mockGet.mock.calls.length;
+    // Sanity: 2 visible nodes (ws-a, ws-b) → 2 fan-out requests on mount
+    expect(callsAfterMount).toBe(2);
+
+    // Simulate a store mutation that changes the nodes array reference
+    // (e.g. status flip on a node) WITHOUT changing the set of visible
+    // IDs. Pre-fix: this triggered a re-fetch storm. Post-fix: the
+    // sorted-CSV selector returns the same key, Zustand's shallow-equal
+    // short-circuits, useMemo keeps the same visibleIds, fetchAndUpdate
+    // keeps the same identity, useEffect does NOT re-fire.
+    mockStoreState.nodes = [
+      { id: "ws-a", hidden: false, data: { newStatus: "online" } },  // mutated
+      { id: "ws-b", hidden: false, data: {} },
+      { id: "ws-hidden", hidden: true, data: {} },
+    ];
+    rerender(<A2ATopologyOverlay />);
+    await act(async () => { await Promise.resolve(); await Promise.resolve(); });
+
+    // No additional fetches should have fired.
+    expect(mockGet.mock.calls.length).toBe(callsAfterMount);
+  });
+
+  it("re-fetches when the visible ID set actually changes", async () => {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    mockGet.mockResolvedValue([] as any);
+    const { rerender } = render(<A2ATopologyOverlay />);
+    await act(async () => { await Promise.resolve(); await Promise.resolve(); });
+
+    const callsAfterMount = mockGet.mock.calls.length;
+    expect(callsAfterMount).toBe(2);
+
+    // Add a new visible workspace — the visible-ID-set actually changed.
+    mockStoreState.nodes = [
+      { id: "ws-a", hidden: false, data: {} },
+      { id: "ws-b", hidden: false, data: {} },
+      { id: "ws-c", hidden: false, data: {} }, // NEW
+      { id: "ws-hidden", hidden: true, data: {} },
+    ];
+    rerender(<A2ATopologyOverlay />);
+    await act(async () => { await Promise.resolve(); await Promise.resolve(); });
+
+    // Should have fetched the additional workspace + the existing two
+    // (the effect re-fires once with the new ID set). Total: 2 + 3 = 5.
+    expect(mockGet.mock.calls.length).toBe(callsAfterMount + 3);
+    const allPaths = mockGet.mock.calls.map(([p]) => p as string);
+    expect(allPaths.some((p) => p.includes("ws-c"))).toBe(true);
+  });
 });
@@ -130,6 +130,26 @@ describe("BatchActionBar", () => {
    const toolbar = screen.getByRole("toolbar");
    expect(toolbar.getAttribute("aria-label")).toBe("Batch workspace actions");
  });
+
+  it("Esc clears the selection — matches the deselect button title", () => {
+    // The deselect button has been promising "Clear selection (Escape)"
+    // since the bar shipped, but no handler was wired. This pins the
+    // contract.
+    mockSelectedNodeIds = new Set(["ws-1", "ws-2"]);
+    render(<BatchActionBar />);
+    fireEvent.keyDown(window, { key: "Escape" });
+    expect(mockClearSelection).toHaveBeenCalled();
+  });
+
+  it("Esc is a no-op when nothing is selected", () => {
+    mockSelectedNodeIds = new Set<string>();
+    render(<BatchActionBar />);
+    fireEvent.keyDown(window, { key: "Escape" });
+    // The early-return at count===0 prevents the bar from mounting at all,
+    // so the keydown listener never registers. clearSelection must NOT be
+    // called.
+    expect(mockClearSelection).not.toHaveBeenCalled();
+  });
 });

 /**
@@ -0,0 +1,178 @@
+// @vitest-environment jsdom
+/**
+ * CommunicationOverlay tests — pin the rate-limit fix shipped 2026-05-04.
+ *
+ * The overlay polls /workspaces/:id/activity?limit=5 for each online
+ * workspace. Pre-fix it (a) polled regardless of visibility and (b)
+ * fanned out to 6 workspaces every 10s. With 8+ workspaces a user
+ * triggered sustained 429s (server-side rate limit is 600 req/min/IP).
+ *
+ * These tests pin:
+ *  1. Fan-out cap of 3 — even with 6 online nodes, only 3 fetches
+ *  2. Visibility gate — when collapsed, no polling
+ *
+ * If a future refactor pushes either dial back up, CI fails before
+ * the regression hits a paying tenant.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, cleanup, act, fireEvent } from "@testing-library/react";
+
+// ── Mocks (hoisted before imports) ────────────────────────────────────────────
+
+vi.mock("@/lib/api", () => ({
+  api: { get: vi.fn() },
+}));
+
+// Six online nodes — enough to verify the cap of 3.
+const mockStoreState = {
+  selectedNodeId: null as string | null,
+  nodes: [
+    { id: "ws-1", data: { status: "online", name: "ws-1" } },
+    { id: "ws-2", data: { status: "online", name: "ws-2" } },
+    { id: "ws-3", data: { status: "online", name: "ws-3" } },
+    { id: "ws-4", data: { status: "online", name: "ws-4" } },
+    { id: "ws-5", data: { status: "online", name: "ws-5" } },
+    { id: "ws-6", data: { status: "online", name: "ws-6" } },
+    { id: "ws-offline", data: { status: "offline", name: "off" } },
+  ],
+};
+
+vi.mock("@/store/canvas", () => ({
+  useCanvasStore: vi.fn(
+    (selector: (s: typeof mockStoreState) => unknown) =>
+      selector(mockStoreState)
+  ),
+}));
+
+// design-tokens has named exports — keep the shape minimal.
+vi.mock("@/lib/design-tokens", () => ({
+  COMM_TYPE_LABELS: {
+    a2a_send: "→",
+    a2a_receive: "←",
+    task_update: "✓",
+  },
+}));
+
+// ── Imports (after mocks) ─────────────────────────────────────────────────────
+
+import { api } from "@/lib/api";
+import { CommunicationOverlay } from "../CommunicationOverlay";
+
+const mockGet = vi.mocked(api.get);
+
+// ── Setup ─────────────────────────────────────────────────────────────────────
+
+beforeEach(() => {
+  vi.useFakeTimers();
+  mockGet.mockReset();
+  mockGet.mockResolvedValue([]);
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe("CommunicationOverlay — fan-out cap", () => {
+  it("polls at most 3 of 6 online workspaces (rate-limit floor)", async () => {
+    await act(async () => {
+      render(<CommunicationOverlay />);
+    });
+    // Mount fires the first poll synchronously (no interval tick yet).
+    // Pre-fix: 6 calls. Post-fix: 3.
+    expect(mockGet).toHaveBeenCalledTimes(3);
+    // Verify the calls are for the FIRST 3 online nodes (slice order).
+    expect(mockGet).toHaveBeenCalledWith("/workspaces/ws-1/activity?limit=5");
+    expect(mockGet).toHaveBeenCalledWith("/workspaces/ws-2/activity?limit=5");
+    expect(mockGet).toHaveBeenCalledWith("/workspaces/ws-3/activity?limit=5");
+  });
+
+  it("never polls offline workspaces", async () => {
+    await act(async () => {
+      render(<CommunicationOverlay />);
+    });
+    expect(mockGet).not.toHaveBeenCalledWith(
+      "/workspaces/ws-offline/activity?limit=5",
+    );
+  });
+});
+
+describe("CommunicationOverlay — cadence", () => {
+  it("uses 30s interval cadence (was 10s pre-fix)", async () => {
+    await act(async () => {
+      render(<CommunicationOverlay />);
+    });
+    expect(mockGet).toHaveBeenCalledTimes(3); // initial mount poll
+
+    // Advance 10s — pre-fix this would fire another poll. Post-fix: silent.
+    await act(async () => {
+      vi.advanceTimersByTime(10_000);
+    });
+    expect(mockGet).toHaveBeenCalledTimes(3);
+
+    // Advance to 30s — interval fires.
+    await act(async () => {
+      vi.advanceTimersByTime(20_000);
+    });
+    expect(mockGet).toHaveBeenCalledTimes(6); // +3 from second tick
+  });
+});
+
+describe("CommunicationOverlay — visibility gate", () => {
+  // The visibility gate is the dial that drops collapsed-panel polling
+  // to ZERO. The cadence test above can't catch its removal — if a
+  // refactor dropped `if (!visible) return`, the cadence test would
+  // still pass because the effect would still fire every 30s.
+  //
+  // Direct probe: render with comms-returning mock so the panel
+  // actually renders (close button only exists in the expanded panel,
+  // not the collapsed button-state). Click close, advance the clock,
+  // assert no further fetches.
+  it("stops polling after the user collapses the panel", async () => {
+    // Mock returns one a2a_send so comms.length > 0 → panel renders →
+    // close button accessible.
+    mockGet.mockResolvedValue([
+      {
+        id: "act-1",
+        workspace_id: "ws-1",
+        activity_type: "a2a_send",
+        source_id: "ws-1",
+        target_id: "ws-2",
+        summary: "test",
+        status: "completed",
+        duration_ms: 100,
+        created_at: new Date().toISOString(),
+      },
+    ]);
+
+    const { getByLabelText } = await act(async () => {
+      return render(<CommunicationOverlay />);
+    });
+    // Drain pending microtasks (resolves the await in fetchComms) so
+    // setComms lands and the panel renders. Don't advance time — that
+    // would fire the next interval tick and pollute the assertion.
+    await act(async () => {
+      await Promise.resolve();
+      await Promise.resolve();
+      await Promise.resolve();
+    });
+    // Initial mount polled 3 workspaces.
+    expect(mockGet).toHaveBeenCalledTimes(3);
+    mockGet.mockClear();
+
+    // Click the close button. Synchronous getByLabelText avoids
+    // findBy's internal setTimeout (deadlocks under useFakeTimers).
+    const closeBtn = getByLabelText("Close communications panel");
+    await act(async () => {
+      fireEvent.click(closeBtn);
+    });
+
+    // Advance well past the 30s cadence — gate should suppress the tick.
+    await act(async () => {
+      vi.advanceTimersByTime(60_000);
+    });
+    expect(mockGet).not.toHaveBeenCalled();
+  });
+});
@@ -228,4 +228,38 @@ describe("ContextMenu — keyboard accessibility", () => {
    );
    expect(closeContextMenu).toHaveBeenCalled();
  });
+
+  // The "Expand to Team" right-click action was removed in Phase 2 of
+  // RFC #2857 — every workspace can already have children via the
+  // regular CreateWorkspace flow with parent_id, so a separate
+  // backend bulk-create handler (which was non-idempotent and leaked
+  // EC2s on every duplicate call) was deleted in PR #2856 and the
+  // canvas affordance is gone with it.
+  it("'Expand to Team' menu item is gone (childless workspace)", () => {
+    // Default mockStore.nodes = [] → no children → workspace is childless.
+    render(<ContextMenu />);
+    const items = screen.getAllByRole("menuitem");
+    const labels = items.map((el) => el.textContent?.trim() ?? "");
+    // Literal absence — vitest's toContain uses Object.is/===, so the
+    // earlier `.not.toContain(expect.stringMatching(...))` shape passed
+    // for ANY string array (asymmetric matchers only work with toEqual /
+    // arrayContaining). Pin the production string verbatim.
+    expect(labels.some((l) => l.includes("Expand to Team"))).toBe(false);
+    // Sanity: childless menu still has the regular actions.
+    expect(labels.some((l) => l.includes("Delete"))).toBe(true);
+    expect(labels.some((l) => l.includes("Restart"))).toBe(true);
+  });
+
+  it("'Collapse Team' is still present when the workspace HAS children", () => {
+    // Mark a child belonging to ws-1 so hasChildren() returns true.
+    mockStore.nodes = [{ id: "child-1", data: { parentId: "ws-1" } }];
+    render(<ContextMenu />);
+    const items = screen.getAllByRole("menuitem");
+    const labels = items.map((el) => el.textContent?.trim() ?? "");
+    expect(labels.some((l) => /Collapse Team|Expand Team/.test(l))).toBe(true);
+    expect(labels.some((l) => l.includes("Arrange Children"))).toBe(true);
+    expect(labels.some((l) => l.includes("Zoom to Team"))).toBe(true);
+    // Cleanup for other tests.
+    mockStore.nodes = [];
+  });
 });
@@ -40,7 +40,7 @@ afterEach(() => {
 describe("CookieConsent", () => {
  it("renders the banner when no decision is stored", () => {
    render(<CookieConsent />);
-    expect(screen.getByRole("dialog")).toBeTruthy();
+    expect(screen.getByRole("region")).toBeTruthy();
    expect(screen.getByRole("button", { name: "Accept all" })).toBeTruthy();
    expect(screen.getByRole("button", { name: "Necessary only" })).toBeTruthy();
  });
@@ -48,7 +48,7 @@ describe("CookieConsent", () => {
  it("stores 'accepted' and hides the banner when user clicks Accept all", () => {
    render(<CookieConsent />);
    fireEvent.click(screen.getByRole("button", { name: "Accept all" }));
-    expect(screen.queryByRole("dialog")).toBeNull();
+    expect(screen.queryByRole("region")).toBeNull();

    const raw = window.localStorage.getItem(STORAGE_KEY);
    expect(raw).not.toBeNull();
@@ -61,7 +61,7 @@ describe("CookieConsent", () => {
  it("stores 'rejected' and hides the banner when user clicks Necessary only", () => {
    render(<CookieConsent />);
    fireEvent.click(screen.getByRole("button", { name: "Necessary only" }));
-    expect(screen.queryByRole("dialog")).toBeNull();
+    expect(screen.queryByRole("region")).toBeNull();

    const parsed = JSON.parse(window.localStorage.getItem(STORAGE_KEY)!);
    expect(parsed.decision).toBe("rejected");
@@ -73,7 +73,7 @@ describe("CookieConsent", () => {
      JSON.stringify({ decision: "accepted", decidedAt: new Date().toISOString(), version: 1 }),
    );
    render(<CookieConsent />);
-    expect(screen.queryByRole("dialog")).toBeNull();
+    expect(screen.queryByRole("region")).toBeNull();
  });

  it("re-prompts when the stored decision is on an older policy version", () => {
@@ -82,13 +82,13 @@ describe("CookieConsent", () => {
      JSON.stringify({ decision: "accepted", decidedAt: new Date().toISOString(), version: 0 }),
    );
    render(<CookieConsent />);
-    expect(screen.getByRole("dialog")).toBeTruthy();
+    expect(screen.getByRole("region")).toBeTruthy();
  });

  it("re-prompts when localStorage contains invalid JSON", () => {
    window.localStorage.setItem(STORAGE_KEY, "{not json");
    render(<CookieConsent />);
-    expect(screen.getByRole("dialog")).toBeTruthy();
+    expect(screen.getByRole("region")).toBeTruthy();
  });

  it("exposes a privacy-policy link with target='_blank'", () => {
@@ -99,11 +99,19 @@ describe("CookieConsent", () => {
    expect(link.getAttribute("rel")).toContain("noreferrer");
  });

-  it("uses role=dialog with aria-labelledby and aria-describedby for screen readers", () => {
+  it("uses role=region (NOT dialog) with aria-labelledby/describedby — banner is informational, not modal", () => {
+    // Regression guard: an earlier version claimed role="dialog"
+    // aria-modal="true" without a focus trap. That falsely told screen
+    // readers the rest of the page was inert, trapping AT users in a
+    // banner they couldn't escape. role="region" lets assistive tech
+    // navigate around it normally; the banner stays informational.
    render(<CookieConsent />);
-    const dialog = screen.getByRole("dialog");
-    expect(dialog.getAttribute("aria-labelledby")).toBe("cookie-consent-title");
-    expect(dialog.getAttribute("aria-describedby")).toBe("cookie-consent-body");
+    const banner = screen.getByRole("region");
+    expect(banner.getAttribute("aria-labelledby")).toBe("cookie-consent-title");
+    expect(banner.getAttribute("aria-describedby")).toBe("cookie-consent-body");
+    // No aria-modal claim — explicit guard against regression.
+    expect(banner.getAttribute("aria-modal")).toBeNull();
+    expect(screen.queryByRole("dialog")).toBeNull();
  });

  it("does NOT render on local dev (non-SaaS hostname)", () => {
@@ -116,7 +124,7 @@ describe("CookieConsent", () => {
      value: { ...window.location, hostname: "localhost" },
    });
    render(<CookieConsent />);
-    expect(screen.queryByRole("dialog")).toBeNull();
+    expect(screen.queryByRole("region")).toBeNull();
  });

  it("does NOT render on a LAN hostname (192.168.*, *.local)", () => {
@@ -125,7 +133,7 @@ describe("CookieConsent", () => {
      value: { ...window.location, hostname: "192.168.1.74" },
    });
    render(<CookieConsent />);
-    expect(screen.queryByRole("dialog")).toBeNull();
+    expect(screen.queryByRole("region")).toBeNull();
  });
 });

@@ -0,0 +1,202 @@
+// @vitest-environment jsdom
+/**
+ * MemoryEditorDialog tests — covers Add (POST /memories) and Edit
+ * (PATCH /memories/:id) flows. Pins:
+ *   - Add posts {content, scope, namespace} with the trimmed defaults
+ *   - Edit only sends fields that changed (no-op edit short-circuits, no PATCH fires)
+ *   - Empty content blocks save
+ *   - Save error surfaces in the dialog and keeps the modal open
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent, waitFor, cleanup } from "@testing-library/react";
+
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: vi.fn(),
+    post: vi.fn(),
+    patch: vi.fn(),
+    del: vi.fn(),
+  },
+}));
+
+import { api } from "@/lib/api";
+import { MemoryEditorDialog } from "../MemoryEditorDialog";
+import type { MemoryEntry } from "../MemoryInspectorPanel";
+
+const mockPost = vi.mocked(api.post);
+const mockPatch = vi.mocked(api.patch);
+
+const SAMPLE: MemoryEntry = {
+  id: "mem-x",
+  workspace_id: "ws-1",
+  content: "original content",
+  scope: "TEAM",
+  namespace: "procedures",
+  created_at: "2026-04-17T12:00:00.000Z",
+};
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  mockPost.mockResolvedValue({} as never);
+  mockPatch.mockResolvedValue({} as never);
+});
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("Add mode", () => {
+  it("POSTs scope+namespace+trimmed-content and calls onSaved+onClose", async () => {
+    const onClose = vi.fn();
+    const onSaved = vi.fn();
+    render(
+      <MemoryEditorDialog
+        open
+        mode="add"
+        workspaceId="ws-1"
+        defaultScope="GLOBAL"
+        defaultNamespace="facts"
+        onClose={onClose}
+        onSaved={onSaved}
+      />,
+    );
+
+    const textarea = screen.getByLabelText(/Content/i) as HTMLTextAreaElement;
+    fireEvent.change(textarea, { target: { value: "  new fact  " } });
+
+    fireEvent.click(screen.getByRole("button", { name: /Add memory$/i }));
+
+    await waitFor(() => expect(mockPost).toHaveBeenCalledTimes(1));
+    expect(mockPost).toHaveBeenCalledWith("/workspaces/ws-1/memories", {
+      content: "new fact",
+      scope: "GLOBAL",
+      namespace: "facts",
+    });
+    expect(onSaved).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("blocks save when content is empty (whitespace-only)", () => {
+    const onClose = vi.fn();
+    const onSaved = vi.fn();
+    render(
+      <MemoryEditorDialog
+        open
+        mode="add"
+        workspaceId="ws-1"
+        defaultScope="LOCAL"
+        onClose={onClose}
+        onSaved={onSaved}
+      />,
+    );
+    const textarea = screen.getByLabelText(/Content/i) as HTMLTextAreaElement;
+    fireEvent.change(textarea, { target: { value: "   " } });
+    fireEvent.click(screen.getByRole("button", { name: /Add memory$/i }));
+    expect(mockPost).not.toHaveBeenCalled();
+    expect(screen.getByRole("alert").textContent).toMatch(/empty/i);
+    expect(onSaved).not.toHaveBeenCalled();
+    expect(onClose).not.toHaveBeenCalled();
+  });
+});
+
+describe("Edit mode", () => {
+  it("PATCHes only changed fields", async () => {
+    const onClose = vi.fn();
+    const onSaved = vi.fn();
+    render(
+      <MemoryEditorDialog
+        open
+        mode="edit"
+        workspaceId="ws-1"
+        entry={SAMPLE}
+        onClose={onClose}
+        onSaved={onSaved}
+      />,
+    );
+
+    const textarea = screen.getByLabelText(/Content/i) as HTMLTextAreaElement;
+    fireEvent.change(textarea, { target: { value: "rewritten content" } });
+    // namespace untouched
+
+    fireEvent.click(screen.getByRole("button", { name: /Save changes/i }));
+
+    await waitFor(() => expect(mockPatch).toHaveBeenCalledTimes(1));
+    expect(mockPatch).toHaveBeenCalledWith(
+      "/workspaces/ws-1/memories/mem-x",
+      { content: "rewritten content" },
+    );
+    expect(onSaved).toHaveBeenCalledTimes(1);
+    expect(onClose).toHaveBeenCalledTimes(1);
+  });
+
+  it("no-op edit short-circuits (no PATCH fires) and still closes", async () => {
+    const onClose = vi.fn();
+    const onSaved = vi.fn();
+    render(
+      <MemoryEditorDialog
+        open
+        mode="edit"
+        workspaceId="ws-1"
+        entry={SAMPLE}
+        onClose={onClose}
+        onSaved={onSaved}
+      />,
+    );
+    fireEvent.click(screen.getByRole("button", { name: /Save changes/i }));
+    await waitFor(() => expect(onClose).toHaveBeenCalled());
+    expect(mockPatch).not.toHaveBeenCalled();
+    expect(onSaved).toHaveBeenCalledTimes(1);
+  });
+
+  it("sends namespace too when both content and namespace changed", async () => {
+    const onClose = vi.fn();
+    const onSaved = vi.fn();
+    render(
+      <MemoryEditorDialog
+        open
+        mode="edit"
+        workspaceId="ws-1"
+        entry={SAMPLE}
+        onClose={onClose}
+        onSaved={onSaved}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText(/Content/i), {
+      target: { value: "newer content" },
+    });
+    fireEvent.change(screen.getByLabelText(/Namespace/i), {
+      target: { value: "blockers" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /Save changes/i }));
+    await waitFor(() => expect(mockPatch).toHaveBeenCalledTimes(1));
+    expect(mockPatch).toHaveBeenCalledWith(
+      "/workspaces/ws-1/memories/mem-x",
+      { content: "newer content", namespace: "blockers" },
+    );
+  });
+
+  it("surfaces save error and keeps the modal open", async () => {
+    const onClose = vi.fn();
+    const onSaved = vi.fn();
+    mockPatch.mockRejectedValueOnce(new Error("boom"));
+    render(
+      <MemoryEditorDialog
+        open
+        mode="edit"
+        workspaceId="ws-1"
+        entry={SAMPLE}
+        onClose={onClose}
+        onSaved={onSaved}
+      />,
+    );
+    fireEvent.change(screen.getByLabelText(/Content/i), {
+      target: { value: "rewritten content" },
+    });
+    fireEvent.click(screen.getByRole("button", { name: /Save changes/i }));
+    await waitFor(() =>
+      expect(screen.getByRole("alert").textContent).toMatch(/boom/),
+    );
+    expect(onClose).not.toHaveBeenCalled();
+    expect(onSaved).not.toHaveBeenCalled();
+  });
+});
@@ -155,18 +155,31 @@ describe("SearchDialog — keyboard accessibility", () => {
    expect(selectNode).not.toHaveBeenCalled();
  });

-  it("typing a new query resets focusedIndex to -1", () => {
+  it("typing a query that matches auto-highlights the first result", () => {
+    // Replaces the older "resets to -1" assertion. New behavior: a query
+    // with at least one match pins the highlight to row 0 so Enter picks
+    // a result instead of being a no-op. Empty-query case is covered by
+    // "Enter at focusedIndex=-1 does not select anything" above.
+    render(<SearchDialog />);
+    const input = screen.getByRole("combobox");
+    fireEvent.change(input, { target: { value: "Alpha" } });
+    const options = screen.getAllByRole("option");
+    expect(options[0].getAttribute("aria-selected")).toBe("true");
+    // Enter on the auto-highlighted match should select it without
+    // needing a manual ArrowDown first.
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(selectNode).toHaveBeenCalledWith("ws-1");
+  });
+
+  it("typing a query that matches NOTHING resets focusedIndex to -1", () => {
    render(<SearchDialog />);
    const input = screen.getByRole("combobox");
    fireEvent.keyDown(input, { key: "ArrowDown" }); // focusedIndex → 0
-    // Verify selection before reset
-    expect(screen.getAllByRole("option")[0].getAttribute("aria-selected")).toBe("true");
-    // Change query — triggers the useEffect that resets focusedIndex
-    fireEvent.change(input, { target: { value: "Alpha" } });
-    // After reset all options must have aria-selected="false"
-    screen.getAllByRole("option").forEach((opt) => {
-      expect(opt.getAttribute("aria-selected")).toBe("false");
-    });
+    fireEvent.change(input, { target: { value: "zzz-no-match" } });
+    // No options remain, so nothing to assert on aria-selected directly —
+    // the empty-state message takes over. But Enter should be a no-op.
+    fireEvent.keyDown(input, { key: "Enter" });
+    expect(selectNode).not.toHaveBeenCalled();
  });

  it("aria-activedescendant matches the focused option's id", () => {
@@ -0,0 +1,82 @@
+// @vitest-environment jsdom
+import { describe, it, expect, afterEach, beforeEach, vi } from "vitest";
+import { render, screen, fireEvent, cleanup, act } from "@testing-library/react";
+import { Toaster, showToast } from "../Toaster";
+
+beforeEach(() => {
+  vi.useFakeTimers();
+});
+
+afterEach(() => {
+  cleanup();
+  vi.useRealTimers();
+});
+
+describe("Toaster keyboard a11y", () => {
+  it("Esc dismisses the most recent toast", () => {
+    render(<Toaster />);
+    act(() => {
+      showToast("first", "info");
+      showToast("second", "info");
+    });
+    expect(screen.getByText("first")).toBeTruthy();
+    expect(screen.getByText("second")).toBeTruthy();
+
+    act(() => {
+      fireEvent.keyDown(window, { key: "Escape" });
+    });
+    expect(screen.queryByText("second")).toBeNull();
+    expect(screen.getByText("first")).toBeTruthy();
+  });
+
+  it("Esc dismisses persistent error toasts", () => {
+    render(<Toaster />);
+    act(() => {
+      showToast("boom", "error");
+    });
+    expect(screen.getByText("boom")).toBeTruthy();
+
+    act(() => {
+      fireEvent.keyDown(window, { key: "Escape" });
+    });
+    expect(screen.queryByText("boom")).toBeNull();
+  });
+
+  it("Esc with no toasts is a no-op", () => {
+    render(<Toaster />);
+    act(() => {
+      fireEvent.keyDown(window, { key: "Escape" });
+    });
+    // no throw, nothing rendered
+    expect(screen.queryAllByRole("button", { name: "Dismiss notification" })).toHaveLength(0);
+  });
+
+  it("dismiss button has accessible label and is keyboard reachable", () => {
+    render(<Toaster />);
+    act(() => {
+      showToast("hi", "info");
+    });
+    const btn = screen.getByRole("button", { name: "Dismiss notification" });
+    expect(btn).toBeTruthy();
+    // Native <button> defaults to keyboard-focusable; explicit assertion guards
+    // against a future regression where someone adds tabindex=-1.
+    expect(btn.getAttribute("tabindex")).not.toBe("-1");
+  });
+
+  it("dismiss button click removes that specific toast", () => {
+    render(<Toaster />);
+    act(() => {
+      showToast("a", "info");
+      showToast("b", "info");
+    });
+    const buttons = screen.getAllByRole("button", { name: "Dismiss notification" });
+    expect(buttons).toHaveLength(2);
+
+    // Click the first dismiss → "a" goes away, "b" stays
+    act(() => {
+      fireEvent.click(buttons[0]);
+    });
+    expect(screen.queryByText("a")).toBeNull();
+    expect(screen.getByText("b")).toBeTruthy();
+  });
+});
@@ -110,8 +110,11 @@ export function ActivityTab({ workspaceId }: Props) {
              Full Trace
            </button>
            <button
+              type="button"
              onClick={loadActivities}
-              className="px-2 py-1 bg-surface-card hover:bg-surface-card text-[11px] rounded text-ink-mid"
+              // hover:bg-surface-card on top of itself was a no-op;
+              // lift to surface-elevated + focus-visible ring.
+              className="px-2 py-1 bg-surface-card hover:bg-surface-elevated hover:text-ink text-[11px] rounded text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/50"
            >
              Refresh
            </button>
@@ -365,8 +365,12 @@ export function ChannelsTab({ workspaceId }: Props) {
            <p className="text-[10px] text-bad">{formError}</p>
          )}
          <button
+            type="button"
            onClick={handleCreate}
-            className="w-full text-xs py-1.5 rounded bg-accent-strong hover:bg-accent text-white transition"
+            // Was bg-accent-strong hover:bg-accent — accent is the
+            // LIGHTER variant; same AA contrast trap fixed in
+            // ScheduleTab/MemoryTab/OnboardingWizard.
+            className="w-full text-xs py-1.5 rounded bg-accent hover:bg-accent-strong text-white transition focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
          >
            Connect Channel
          </button>
@@ -1,6 +1,6 @@
 "use client";

-import { useState, useRef, useEffect, useCallback } from "react";
+import { useState, useRef, useEffect, useCallback, useLayoutEffect } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { api } from "@/lib/api";
@@ -124,14 +124,43 @@ function extractReplyText(resp: A2AResponse): string {
 // doesn't). Single source of truth for file-part parsing across
 // live chat, activity log replay, and any future consumers.

+/** Initial chat history page size. The newest N messages are rendered
+ *  on first paint; older history is fetched on demand via loadOlder()
+ *  when the user scrolls the top sentinel into view. */
+const INITIAL_HISTORY_LIMIT = 10;
+/** Subsequent older-history batch size. Larger than INITIAL so a long
+ *  scroll-back doesn't fan out into many round-trips. */
+const OLDER_HISTORY_BATCH = 20;
+
 /**
 * Load chat history from the activity_logs database via the platform API.
 * Uses source=canvas to only get user-initiated messages (not agent-to-agent).
+ *
+ * Pagination:
+ *  - Pass `limit` to bound the page size (newest-first from server).
+ *  - Pass `beforeTs` (RFC3339) to fetch rows STRICTLY OLDER than that
+ *    timestamp. Combined with limit, this yields the next-older page
+ *    when scrolling backward through history.
+ *
+ * `reachedEnd` is true when the server returned fewer rows than asked
+ * for — caller uses this to disable further older-batch fetches.
+ * (Counts row-level returns, not chat-bubble count: each row may
+ * produce 1-2 bubbles.)
 */
-async function loadMessagesFromDB(workspaceId: string): Promise<{ messages: ChatMessage[]; error: string | null }> {
+async function loadMessagesFromDB(
+  workspaceId: string,
+  limit: number,
+  beforeTs?: string,
+): Promise<{ messages: ChatMessage[]; error: string | null; reachedEnd: boolean }> {
  try {
+    const params = new URLSearchParams({
+      type: "a2a_receive",
+      source: "canvas",
+      limit: String(limit),
+    });
+    if (beforeTs) params.set("before_ts", beforeTs);
    const activities = await api.get<ActivityRowForHydration[]>(
-      `/workspaces/${workspaceId}/activity?type=a2a_receive&source=canvas&limit=50`,
+      `/workspaces/${workspaceId}/activity?${params.toString()}`,
    );

    const messages: ChatMessage[] = [];
@@ -142,11 +171,12 @@ async function loadMessagesFromDB(workspaceId: string): Promise<{ messages: Chat
    for (const a of [...activities].reverse()) {
      messages.push(...activityRowToMessages(a, isInternalSelfMessage));
    }
-    return { messages, error: null };
+    return { messages, error: null, reachedEnd: activities.length < limit };
  } catch (err) {
    return {
      messages: [],
      error: err instanceof Error ? err.message : "Failed to load chat history",
+      reachedEnd: true,
    };
  }
 }
@@ -177,10 +207,10 @@ export function ChatTab({ workspaceId, data }: Props) {
          aria-controls="chat-panel-my-chat"
          tabIndex={subTab === "my-chat" ? 0 : -1}
          onClick={() => setSubTab("my-chat")}
-          className={`px-3 py-1.5 text-[10px] font-medium transition-colors ${
+          className={`px-3 py-1.5 text-[10px] font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${
            subTab === "my-chat"
              ? "text-ink border-b-2 border-accent"
-              : "text-ink-soft hover:text-ink-mid"
+              : "text-ink-mid hover:text-ink"
          }`}
        >
          My Chat
@@ -192,10 +222,10 @@ export function ChatTab({ workspaceId, data }: Props) {
          aria-controls="chat-panel-agent-comms"
          tabIndex={subTab === "agent-comms" ? 0 : -1}
          onClick={() => setSubTab("agent-comms")}
-          className={`px-3 py-1.5 text-[10px] font-medium transition-colors ${
+          className={`px-3 py-1.5 text-[10px] font-medium transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 ${
            subTab === "agent-comms"
              ? "text-ink border-b-2 border-accent"
-              : "text-ink-soft hover:text-ink-mid"
+              : "text-ink-mid hover:text-ink"
          }`}
        >
          Agent Comms
@@ -256,6 +286,60 @@ function MyChatPanel({ workspaceId, data }: Props) {
  const [error, setError] = useState<string | null>(null);
  const [confirmRestart, setConfirmRestart] = useState(false);
  const bottomRef = useRef<HTMLDivElement>(null);
+  // First-mount scroll-to-bottom needs `behavior: "instant"` — long
+  // conversations smooth-animate for ~300ms which any concurrent
+  // re-render can interrupt, leaving the user stuck mid-conversation
+  // when the chat tab opens. Subsequent appends (new agent messages)
+  // keep `smooth` for the visual "landing" feel. Flipped the first
+  // time messages.length goes positive, so a workspace switch (which
+  // remounts ChatTab) gets a fresh instant jump too.
+  const hasInitialScrollRef = useRef(false);
+  // Lazy-load older history on scroll-up.
+  // - containerRef = the scrollable messages viewport
+  // - topRef       = sentinel above the messages list; IO observes it
+  //                  and triggers loadOlder() when it enters view
+  // - hasMore      = false once a fetch returns < limit rows; stops IO
+  // - loadingOlder = drives the "Loading older messages…" UI label
+  // - inflightRef  = synchronous guard against double-entry of loadOlder
+  //                  when the IO callback fires twice in the same
+  //                  microtask (state-based guard would be stale until
+  //                  the next React commit)
+  // - scrollAnchorRef = saves distance-from-bottom before a prepend
+  //                  so the useLayoutEffect below can restore the
+  //                  user's exact viewport position. Without this,
+  //                  prepending older messages would jump the scroll
+  //                  position by the height of the new content.
+  // - oldestMessageRef / hasMoreRef = let the loadOlder closure read
+  //                  the latest values without taking them as deps —
+  //                  every live agent push mutates `messages`, and
+  //                  having loadOlder depend on `messages` would tear
+  //                  down + re-arm the IntersectionObserver on every
+  //                  push. Refs decouple the observer lifecycle from
+  //                  message-list updates.
+  const containerRef = useRef<HTMLDivElement>(null);
+  const topRef = useRef<HTMLDivElement>(null);
+  const [hasMore, setHasMore] = useState(true);
+  const [loadingOlder, setLoadingOlder] = useState(false);
+  const inflightRef = useRef(false);
+  // The scroll anchor includes the first-message id as it was BEFORE
+  // the prepend — see useLayoutEffect below for why. Without this tag,
+  // a live agent push that appends WHILE loadOlder is in flight would
+  // run useLayoutEffect against the append (anchor still set), the
+  // "restore" math would scroll the user to a stale offset, AND the
+  // append's normal scroll-to-bottom would be swallowed.
+  const scrollAnchorRef = useRef<
+    { savedDistanceFromBottom: number; expectFirstIdNotEqual: string | null } | null
+  >(null);
+  const oldestMessageRef = useRef<ChatMessage | null>(null);
+  const hasMoreRef = useRef(true);
+  // Monotonic token bumped on workspace switch + on every loadOlder
+  // entry. Each fetch's .then() captures its own token; if the token
+  // has moved, the resolved messages belong to a stale workspace or a
+  // superseded fetch and we silently drop them. Without this guard, a
+  // workspace switch mid-fetch would have the in-flight promise
+  // resolve into the new workspace's setMessages — the user sees
+  // someone else's history briefly.
+  const fetchTokenRef = useRef(0);
  // Files the user has picked but not yet sent. Cleared on send
  // (upload success) or by the × on each pill.
  const [pendingFiles, setPendingFiles] = useState<File[]>([]);
@@ -294,17 +378,144 @@ function MyChatPanel({ workspaceId, data }: Props) {
    sendInFlightRef.current = false;
  }, []);

-  // Load chat history from database on mount
-  useEffect(() => {
+  // Initial-load fetch — used by the mount effect and the "Retry"
+  // button below. Single source of truth so the two paths can't drift
+  // (e.g. INITIAL_HISTORY_LIMIT bumped in the effect but not the
+  // retry, leading to inconsistent first-paint sizes).
+  const loadInitial = useCallback(() => {
    setLoading(true);
    setLoadError(null);
-    loadMessagesFromDB(workspaceId).then(({ messages: msgs, error: fetchErr }) => {
-      setMessages(msgs);
-      setLoadError(fetchErr);
-      setLoading(false);
-    });
+    setHasMore(true);
+    // Bump the token; any in-flight fetch from the previous workspace
+    // (or a previous retry) will see token != myToken in its .then()
+    // and silently bail — the late response can't clobber the new
+    // workspace's state.
+    fetchTokenRef.current += 1;
+    const myToken = fetchTokenRef.current;
+    loadMessagesFromDB(workspaceId, INITIAL_HISTORY_LIMIT).then(
+      ({ messages: msgs, error: fetchErr, reachedEnd }) => {
+        if (fetchTokenRef.current !== myToken) return;
+        setMessages(msgs);
+        setLoadError(fetchErr);
+        setHasMore(!reachedEnd);
+        setLoading(false);
+      },
+    );
  }, [workspaceId]);

+  // Load chat history on mount / workspace switch.
+  // Initial load is bounded to INITIAL_HISTORY_LIMIT (newest 10) — the
+  // rest streams in as the user scrolls up via loadOlder() below. Pre-
+  // 2026-05-05 this fetched the newest 50 in one shot; on a long-running
+  // workspace that meant 50× message-bubble paint + DOM cost on every
+  // tab-open even when the user only wanted to read the last few.
+  useEffect(() => {
+    loadInitial();
+  }, [loadInitial]);
+
+  // Mirror the latest oldest-message + hasMore into refs so loadOlder
+  // can read them without taking `messages` as a dep. Every live push
+  // through agentMessages would otherwise recreate loadOlder and tear
+  // down the IO observer.
+  useEffect(() => {
+    oldestMessageRef.current = messages[0] ?? null;
+  }, [messages]);
+  useEffect(() => {
+    hasMoreRef.current = hasMore;
+  }, [hasMore]);
+
+  // Fetch the next-older batch and prepend. Stable identity (deps =
+  // [workspaceId]) so the IntersectionObserver effect below doesn't
+  // re-arm on every messages update.
+  const loadOlder = useCallback(async () => {
+    // inflightRef is the load-bearing guard — synchronous, set BEFORE
+    // any await, so two IO callbacks dispatched in the same microtask
+    // can't both pass. The state checks are defensive secondary
+    // gates for the slow-scroll case.
+    if (inflightRef.current || !hasMoreRef.current) return;
+    const oldest = oldestMessageRef.current;
+    if (!oldest) return;
+    const container = containerRef.current;
+    if (!container) return;
+    inflightRef.current = true;
+    // Capture the user's distance-from-bottom BEFORE we prepend so the
+    // useLayoutEffect can restore it after the new DOM lands. The
+    // expectFirstIdNotEqual tag is what the layout effect checks
+    // against `messages[0].id` to disambiguate prepend (id changed) vs
+    // append (id unchanged → live message landed mid-fetch). Without
+    // it, an agent push during loadOlder runs the "restore" against a
+    // stale anchor — user gets yanked + the append's bottom-pin is
+    // swallowed.
+    scrollAnchorRef.current = {
+      savedDistanceFromBottom: container.scrollHeight - container.scrollTop,
+      expectFirstIdNotEqual: oldest.id,
+    };
+    fetchTokenRef.current += 1;
+    const myToken = fetchTokenRef.current;
+    setLoadingOlder(true);
+    try {
+      const { messages: older, reachedEnd } = await loadMessagesFromDB(
+        workspaceId,
+        OLDER_HISTORY_BATCH,
+        oldest.timestamp,
+      );
+      // Workspace switched (or another loadOlder bumped the token)
+      // mid-fetch — drop these results, they belong to a stale tab.
+      if (fetchTokenRef.current !== myToken) {
+        scrollAnchorRef.current = null;
+        return;
+      }
+      if (older.length > 0) {
+        setMessages((prev) => [...older, ...prev]);
+      } else {
+        // Nothing came back — clear the anchor so the next paint doesn't
+        // try to "restore" against a no-op prepend.
+        scrollAnchorRef.current = null;
+      }
+      setHasMore(!reachedEnd);
+    } finally {
+      setLoadingOlder(false);
+      inflightRef.current = false;
+    }
+  }, [workspaceId]);
+
+  // IntersectionObserver on the top sentinel. Fires loadOlder() the
+  // moment the user scrolls within 200px of the top. AbortController
+  // unwires cleanly on workspace switch / unmount; root is the
+  // scrollable container so we observe only what's visible inside it.
+  //
+  // Dependencies:
+  //  - loadOlder    — stable per workspaceId (refs decouple it from
+  //                   message updates), so this dep is here for the
+  //                   workspace-switch case only
+  //  - hasMore      — re-run when older history runs out so we
+  //                   disconnect cleanly
+  //  - hasMessages  — load-bearing: the sentinel JSX is gated on
+  //                   `messages.length > 0`, so topRef.current is null
+  //                   on the empty-messages render. We re-arm exactly
+  //                   once when messages first land. NOT depending on
+  //                   `messages.length` (or `messages`) directly so
+  //                   each subsequent message append doesn't tear down
+  //                   + re-arm the observer.
+  const hasMessages = messages.length > 0;
+  useEffect(() => {
+    const top = topRef.current;
+    const container = containerRef.current;
+    if (!top || !container) return;
+    if (!hasMore) return; // stop observing when no older history exists
+    const ac = new AbortController();
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (ac.signal.aborted) return;
+        if (entries[0]?.isIntersecting) loadOlder();
+      },
+      { root: container, rootMargin: "200px 0px 0px 0px", threshold: 0 },
+    );
+    io.observe(top);
+    ac.signal.addEventListener("abort", () => io.disconnect());
+    return () => ac.abort();
+  }, [loadOlder, hasMore, hasMessages]);
+
  // Agent reachability
  useEffect(() => {
    const reachable = data.status === "online" || data.status === "degraded";
@@ -316,7 +527,41 @@ function MyChatPanel({ workspaceId, data }: Props) {
    currentTaskRef.current = data.currentTask;
  }, [data.currentTask]);

-  useEffect(() => {
+  // Scroll behavior across messages updates:
+  //  - Prepend (loadOlder landed)  → restore the user's saved
+  //    distance-from-bottom so their reading position is unchanged.
+  //  - Append / initial            → pin to latest bubble.
+  // useLayoutEffect (not useEffect) so scroll restoration runs BEFORE
+  // paint — otherwise the user sees the page jump for one frame.
+  useLayoutEffect(() => {
+    const container = containerRef.current;
+    const anchor = scrollAnchorRef.current;
+    // Only honor the anchor when this messages-update is the prepend
+    // we expected. messages[0].id is the test:
+    //   - prepend  → messages[0] is one of the older rows → id !== expectFirstIdNotEqual
+    //   - append   → messages[0] unchanged → id === expectFirstIdNotEqual → fall through
+    // Without this check, an agent push that lands mid-loadOlder would
+    // run the restore against the append's update, yank the user's
+    // scroll, AND swallow the append's bottom-pin.
+    if (
+      anchor &&
+      container &&
+      messages.length > 0 &&
+      messages[0].id !== anchor.expectFirstIdNotEqual
+    ) {
+      container.scrollTop = container.scrollHeight - anchor.savedDistanceFromBottom;
+      scrollAnchorRef.current = null;
+      return;
+    }
+    // Instant on first arrival of messages — smooth-scroll on a long
+    // conversation gets interrupted by concurrent renders and leaves
+    // the user stuck in the middle. After the first jump, subsequent
+    // appends animate as before.
+    if (!hasInitialScrollRef.current && messages.length > 0) {
+      hasInitialScrollRef.current = true;
+      bottomRef.current?.scrollIntoView({ behavior: "instant" as ScrollBehavior });
+      return;
+    }
    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
  }, [messages]);

@@ -735,7 +980,7 @@ function MyChatPanel({ workspaceId, data }: Props) {
        </div>
      )}
      {/* Messages */}
-      <div className="flex-1 overflow-y-auto p-3 space-y-3">
+      <div ref={containerRef} className="flex-1 overflow-y-auto p-3 space-y-3">
        {loading && (
          <div className="text-xs text-ink-soft text-center py-4">Loading chat history...</div>
        )}
@@ -748,15 +993,7 @@ function MyChatPanel({ workspaceId, data }: Props) {
              Failed to load chat history: {loadError}
            </p>
            <button
-              onClick={() => {
-                setLoading(true);
-                setLoadError(null);
-                loadMessagesFromDB(workspaceId).then(({ messages: msgs, error: fetchErr }) => {
-                  setMessages(msgs);
-                  setLoadError(fetchErr);
-                  setLoading(false);
-                });
-              }}
+              onClick={loadInitial}
              className="text-[10px] px-2 py-0.5 rounded bg-red-800/40 text-bad hover:bg-red-700/50 transition-colors"
            >
              Retry
@@ -768,19 +1005,62 @@ function MyChatPanel({ workspaceId, data }: Props) {
            No messages yet. Send a message to start chatting with this agent.
          </div>
        )}
+        {/* Top sentinel for lazy-loading older history. The IO observer
+            in the effect above watches this; entering view triggers the
+            next-older batch fetch. Sits ABOVE messages.map so it's the
+            first thing the user reaches when scrolling up.
+
+            Only mounted when there might be more history (hasMore) so a
+            short conversation doesn't pay an idle observer. The
+            "Loading older messages…" line replaces the sentinel during
+            the fetch so the user sees feedback for the scroll-up
+            gesture. Once we hit the end, we drop the sentinel entirely
+            instead of showing a "no more messages" footer — the user's
+            scroll resting against the top of the conversation IS the
+            signal. */}
+        {hasMore && messages.length > 0 && (
+          <div ref={topRef} className="text-xs text-ink-soft text-center py-1">
+            {loadingOlder ? "Loading older messages…" : " "}
+          </div>
+        )}
        {messages.map((msg) => (
          <div key={msg.id} className={`flex ${msg.role === "user" ? "justify-end" : "justify-start"}`}>
            <div
              className={`max-w-[85%] rounded-lg px-3 py-2 text-xs ${
                msg.role === "user"
-                  ? "bg-accent text-white border border-accent-strong"
+                  // Solid blue-600 in both modes — `bg-accent` themes
+                  // lighter in dark, dropping white-text contrast to
+                  // ~3:1 (fails AA). blue-600 keeps ~5:1 against white
+                  // on both warm-paper and dark-slate panels.
+                  ? "bg-blue-600 text-white border border-blue-700 dark:bg-blue-500 dark:border-blue-400 shadow-sm"
                  : msg.role === "system"
-                    ? "bg-bad/10 text-bad border border-bad/40"
-                    : "bg-surface-card text-ink border border-line"
+                    // Bump the system bubble's opacity in dark — /10
+                    // overlay was nearly invisible against the dark
+                    // panel bg.
+                    ? "bg-bad/10 text-bad border border-bad/40 dark:bg-bad/25 dark:text-bad dark:border-bad/60"
+                    // Agent bubble in dark: surface-card (#1a1d23) is
+                    // only ~7% lighter than the panel bg-surface
+                    // (#0e1014). Bump to zinc-700 for a clearly
+                    // elevated bubble; light mode keeps the warm
+                    // surface-card tint.
+                    : "bg-surface-card text-ink border border-line dark:bg-zinc-700 dark:text-zinc-100 dark:border-zinc-600 shadow-sm"
              }`}
            >
              {msg.content && (
-                <div className={`prose prose-sm max-w-none [&>p]:mb-1 [&>p:last-child]:mb-0 ${msg.role === "user" ? "prose-invert" : ""}`}>
+                <div
+                  className={`prose prose-sm max-w-none [&>p]:mb-1 [&>p:last-child]:mb-0 ${
+                    msg.role === "user"
+                      ? "prose-invert"
+                      // Agent bubbles in dark mode: invert prose AND brighten
+                      // the body/heading/bold/code tokens. prose-invert's
+                      // default `--tw-prose-invert-body: zinc-300` lands at
+                      // ~5.3:1 against bg-zinc-700 — passes AA but reads
+                      // washed out next to the user bubble's crisp
+                      // white-on-blue (~10:1). Push body to zinc-100 so the
+                      // agent text matches that crispness.
+                      : "dark:prose-invert dark:[--tw-prose-invert-body:theme(colors.zinc.100)] dark:[--tw-prose-invert-headings:theme(colors.white)] dark:[--tw-prose-invert-bold:theme(colors.white)] dark:[--tw-prose-invert-code:theme(colors.zinc.100)]"
+                  }`}
+                >
                  <ReactMarkdown remarkPlugins={[remarkGfm]}>{msg.content}</ReactMarkdown>
                </div>
              )}
@@ -896,7 +1176,7 @@ function MyChatPanel({ workspaceId, data }: Props) {
            placeholder={agentReachable ? "Send a message... (Shift+Enter for new line, paste images to attach)" : `Agent is ${data.status}`}
            disabled={!agentReachable || sending}
            rows={1}
-            className="flex-1 bg-surface-card border border-line rounded-lg px-3 py-2 text-xs text-ink placeholder-zinc-500 focus:outline-none focus:border-accent resize-none disabled:opacity-50"
+            className="flex-1 bg-surface-card border border-line rounded-lg px-3 py-2 text-xs text-ink placeholder-ink-soft dark:bg-zinc-800 dark:border-zinc-600 dark:placeholder-zinc-500 focus:outline-none focus:border-accent focus-visible:ring-2 focus-visible:ring-accent/40 resize-none disabled:opacity-50"
          />
          <button
            onClick={sendMessage}
@@ -6,6 +6,7 @@ import { useCanvasStore } from "@/store/canvas";
 import { type ConfigData, DEFAULT_CONFIG, TextInput, NumberInput, Toggle, TagList, Section } from "./config/form-inputs";
 import { parseYaml, toYaml } from "./config/yaml-utils";
 import { SecretsSection } from "./config/secrets-section";
+import { ExternalConnectionSection } from "./ExternalConnectionSection";
 import {
  ProviderModelSelector,
  buildProviderCatalog,
@@ -65,11 +66,11 @@ function AgentCardSection({ workspaceId }: { workspaceId: string }) {
          {error && <div 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-strong hover:bg-accent text-[10px] rounded text-white disabled:opacity-50">
+              className="px-2 py-1 bg-accent hover:bg-accent-strong text-[10px] rounded text-white disabled:opacity-50 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-1 focus-visible:ring-offset-surface">
              {saving ? "Saving..." : "Save"}
            </button>
            <button type="button" onClick={() => setEditing(false)}
-              className="px-2 py-1 bg-surface-card hover:bg-surface-card text-[10px] rounded text-ink-mid">Cancel</button>
+              className="px-2 py-1 bg-surface-card hover:bg-surface-elevated hover:text-ink text-[10px] rounded text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-1 focus-visible:ring-offset-surface">Cancel</button>
          </div>
        </div>
      ) : (
@@ -886,11 +887,24 @@ export function ConfigTab({ workspaceId }: Props) {
            </Section>
          )}

-          <Section title="Skills & Tools" defaultOpen={false}>
-            <TagList label="Skills" values={config.skills || []} onChange={(v) => update("skills", v)} placeholder="e.g. code-review" />
-            <TagList label="Tools" values={config.tools || []} onChange={(v) => update("tools", v)} placeholder="e.g. web_search, filesystem" />
-            <TagList label="Prompt Files" values={config.prompt_files || []} onChange={(v) => update("prompt_files", v)} placeholder="e.g. system-prompt.md" />
-            <TagList label="Shared Context" values={config.shared_context || []} onChange={(v) => update("shared_context", v)} placeholder="e.g. architecture.md" />
+          {/* Skills + Tools used to live here as TagList inputs. They were
+              redundant with their dedicated tabs:
+              - Skills → managed via SkillsTab (per-workspace skill folders)
+              - Tools  → managed via the Plugins tab (install/uninstall)
+              Editing them here only set the config.yaml field; the
+              actual install/load happened elsewhere. Removed to stop
+              showing the misnamed list-input affordance. */}
+
+          <Section title="Prompt Files" defaultOpen={false}>
+            <p className="text-[10px] text-ink-soft px-1 pb-1">
+              Markdown files that compose this workspace&apos;s system prompt.
+              Loaded in order at boot from the workspace config dir
+              (e.g. <code className="font-mono">system-prompt.md</code>,{' '}
+              <code className="font-mono">CLAUDE.md</code>,{' '}
+              <code className="font-mono">AGENTS.md</code>). Edit the file
+              contents directly via the Files tab.
+            </p>
+            <TagList label="Files (load order)" values={config.prompt_files || []} onChange={(v) => update("prompt_files", v)} placeholder="e.g. system-prompt.md" />
          </Section>

          <Section title="A2A Protocol" defaultOpen={false}>
@@ -947,6 +961,9 @@ export function ConfigTab({ workspaceId }: Props) {
            : "This runtime manages its own config outside the platform template."}
        </div>
      )}
+      {!error && config.runtime === "external" && (
+        <ExternalConnectionSection workspaceId={workspaceId} />
+      )}
      {success && (
        <div className="mx-3 mb-2 px-3 py-1.5 bg-green-900/30 border border-green-800 rounded text-xs text-good">Saved</div>
      )}
@@ -956,7 +973,8 @@ export function ConfigTab({ workspaceId }: Props) {
          type="button"
          onClick={() => handleSave(true)}
          disabled={!isDirty || saving}
-          className="px-3 py-1.5 bg-accent-strong hover:bg-accent text-xs rounded text-white disabled:opacity-30 transition-colors"
+          // Same accent-LIGHTER fix shipped on every other tab.
+          className="px-3 py-1.5 bg-accent hover:bg-accent-strong text-xs rounded text-white disabled:opacity-30 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-1 focus-visible:ring-offset-surface"
        >
          {saving ? "Restarting..." : "Save & Restart"}
        </button>
@@ -166,7 +166,10 @@ export function DetailsTab({ workspaceId, data }: Props) {
                type="button"
                onClick={handleSave}
                disabled={saving}
-                className="px-3 py-1 bg-accent-strong hover:bg-accent text-xs rounded text-white disabled:opacity-50"
+                // Was bg-accent-strong hover:bg-accent — accent is the
+                // LIGHTER variant; flipped + focus-visible ring (same
+                // trap fix shipped on every other tab).
+                className="px-3 py-1 bg-accent hover:bg-accent-strong text-xs rounded text-white disabled:opacity-50 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-1 focus-visible:ring-offset-surface"
              >
                {saving ? "Saving..." : "Save"}
              </button>
@@ -322,7 +325,10 @@ export function DetailsTab({ workspaceId, data }: Props) {
              <button
                type="button"
                onClick={handleDelete}
-                className="px-3 py-1 bg-red-600 hover:bg-red-500 text-xs rounded text-white"
+                // hover:bg-red-500 LIGHTER on white text drops AA;
+                // flipped to bg-red-700 + focus-visible danger ring,
+                // matching the ConfirmDialog/DeleteCascade pattern.
+                className="px-3 py-1 bg-red-600 hover:bg-red-700 text-xs 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"
              >
                Confirm Delete
              </button>
@@ -334,7 +340,9 @@ export function DetailsTab({ workspaceId, data }: Props) {
                  // Return focus to the trigger so keyboard users aren't stranded
                  deleteButtonRef.current?.focus();
                }}
-                className="px-3 py-1 bg-surface-card hover:bg-surface-card text-xs rounded text-ink-mid"
+                // Was hover:bg-surface-card on top of itself (no-op);
+                // lift to surface-elevated.
+                className="px-3 py-1 bg-surface-card hover:bg-surface-elevated hover:text-ink text-xs rounded text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-1 focus-visible:ring-offset-surface"
              >
                Cancel
              </button>
@@ -15,14 +15,20 @@ interface EventEntry {
  created_at: string;
 }

+// Use semantic warm-paper tokens so colors flip with theme. Earlier
+// the table referenced text-yellow-400 / text-purple-400 (Tailwind
+// raw colors, no theme variant), which read fine in dark mode but
+// washed out in the warm-paper light theme. text-warm covers the
+// "degraded" amber tone in both modes; AGENT_CARD_UPDATED is informational
+// metadata, so reuse text-accent for theme-consistency.
 const EVENT_COLORS: Record<string, string> = {
  WORKSPACE_ONLINE: "text-good",
  WORKSPACE_OFFLINE: "text-ink-mid",
-  WORKSPACE_DEGRADED: "text-yellow-400",
+  WORKSPACE_DEGRADED: "text-warm",
  WORKSPACE_PROVISIONING: "text-accent",
  WORKSPACE_REMOVED: "text-bad",
  WORKSPACE_PROVISION_FAILED: "text-bad",
-  AGENT_CARD_UPDATED: "text-purple-400",
+  AGENT_CARD_UPDATED: "text-accent",
 };

 export function EventsTab({ workspaceId }: Props) {
@@ -64,8 +70,12 @@ export function EventsTab({ workspaceId }: Props) {
      <div className="flex items-center justify-between mb-2">
        <span className="text-xs text-ink-mid">{events.length} events</span>
        <button
+          type="button"
          onClick={loadEvents}
-          className="px-2 py-1 bg-surface-card hover:bg-surface-card text-[10px] rounded text-ink-mid"
+          // Was hover:bg-surface-card on top of bg-surface-card — silent
+          // no-op hover. Lift to surface-elevated, matching the Cancel
+          // pattern from ConfirmDialog.
+          className="px-2 py-1 bg-surface-card hover:bg-surface-elevated hover:text-ink text-[10px] rounded text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/50"
        >
          Refresh
        </button>
@@ -81,39 +91,51 @@ export function EventsTab({ workspaceId }: Props) {
        <p className="text-xs text-ink-soft text-center py-4">No events yet</p>
      ) : (
        <div className="space-y-1">
-          {events.map((event) => (
-            <div key={event.id} className="bg-surface-card rounded border border-line">
-              <button
-                onClick={() => setExpanded(expanded === event.id ? null : event.id)}
-                className="w-full flex items-center gap-2 px-3 py-2 text-left"
-              >
-                <span
-                  className={`text-xs font-mono ${
-                    EVENT_COLORS[event.event_type] || "text-ink-mid"
-                  }`}
+          {events.map((event) => {
+            const isOpen = expanded === event.id;
+            const panelId = `events-payload-${event.id}`;
+            return (
+              <div key={event.id} className="bg-surface-card rounded border border-line">
+                <button
+                  type="button"
+                  onClick={() => setExpanded(isOpen ? null : event.id)}
+                  // aria-expanded + aria-controls so screen readers
+                  // announce the open/closed state and link the row to
+                  // its payload panel. Without these, AT users hear
+                  // a generic "button" with no indication that it
+                  // toggles or what it controls.
+                  aria-expanded={isOpen}
+                  aria-controls={panelId}
+                  className="w-full flex items-center gap-2 px-3 py-2 text-left rounded-t hover:bg-surface-elevated/40 focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-accent/50 transition-colors"
                >
-                  {event.event_type}
-                </span>
-                <span className="text-[9px] text-ink-soft ml-auto">
-                  {formatTime(event.created_at)}
-                </span>
-                <span className="text-[10px] text-ink-soft">
-                  {expanded === event.id ? "▼" : "▶"}
-                </span>
-              </button>
+                  <span
+                    className={`text-xs font-mono ${
+                      EVENT_COLORS[event.event_type] || "text-ink-mid"
+                    }`}
+                  >
+                    {event.event_type}
+                  </span>
+                  <span className="text-[9px] text-ink-soft ml-auto">
+                    {formatTime(event.created_at)}
+                  </span>
+                  <span aria-hidden="true" className="text-[10px] text-ink-soft">
+                    {isOpen ? "▼" : "▶"}
+                  </span>
+                </button>

-              {expanded === event.id && (
-                <div className="px-3 pb-2">
-                  <pre className="text-[10px] text-ink-mid bg-surface-sunken rounded p-2 overflow-x-auto max-h-40">
-                    {JSON.stringify(event.payload, null, 2)}
-                  </pre>
-                  <div className="mt-1 text-[9px] text-ink-soft font-mono">
-                    ID: {event.id}
+                {isOpen && (
+                  <div id={panelId} className="px-3 pb-2">
+                    <pre className="text-[10px] text-ink-mid bg-surface-sunken rounded p-2 overflow-x-auto max-h-40">
+                      {JSON.stringify(event.payload, null, 2)}
+                    </pre>
+                    <div className="mt-1 text-[9px] text-ink-soft font-mono">
+                      ID: {event.id}
+                    </div>
                  </div>
-                </div>
-              )}
-            </div>
-          ))}
+                )}
+              </div>
+            );
+          })}
        </div>
      )}
    </div>
@@ -0,0 +1,146 @@
+'use client';
+
+// ExternalConnectionSection — credential lifecycle controls for runtime=external
+// workspaces. Surfaced inside ConfigTab when the workspace's runtime is
+// "external"; ignored for hermes/claude-code/etc. (those have their own
+// restart-mints-token path).
+//
+// Two affordances:
+//
+//   1. "Show connection info" (read-only)
+//        Fetches GET /workspaces/:id/external/connection. Returns the
+//        connect block (PLATFORM_URL, WORKSPACE_ID, all 7 snippets) WITH
+//        auth_token="". The modal masks the token field and labels it
+//        "rotate to reveal a new token — current token is unrecoverable".
+//
+//   2. "Rotate credentials" (destructive)
+//        POST /workspaces/:id/external/rotate. Revokes any prior live
+//        tokens, mints a fresh one, returns the same connect block with
+//        auth_token populated. Old credentials stop working IMMEDIATELY —
+//        the previously-paired agent will fail auth on its next heartbeat.
+//        Confirm dialog explains this before firing.
+//
+// Reuses the existing ExternalConnectModal so the snippet UX is the
+// same as on Create — operators don't have to learn a second modal.
+
+import { useState } from "react";
+import * as Dialog from "@radix-ui/react-dialog";
+
+import { api } from "@/lib/api";
+import {
+  ExternalConnectModal,
+  type ExternalConnectionInfo,
+} from "../ExternalConnectModal";
+
+interface Props {
+  workspaceId: string;
+}
+
+export function ExternalConnectionSection({ workspaceId }: Props) {
+  const [info, setInfo] = useState<ExternalConnectionInfo | null>(null);
+  const [busy, setBusy] = useState<"show" | "rotate" | null>(null);
+  const [confirmRotate, setConfirmRotate] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  async function showConnection() {
+    setError(null);
+    setBusy("show");
+    try {
+      const resp = await api.get<{ connection: ExternalConnectionInfo }>(
+        `/workspaces/${workspaceId}/external/connection`,
+      );
+      setInfo(resp.connection);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  async function doRotate() {
+    setError(null);
+    setBusy("rotate");
+    setConfirmRotate(false);
+    try {
+      const resp = await api.post<{ connection: ExternalConnectionInfo }>(
+        `/workspaces/${workspaceId}/external/rotate`,
+        {},
+      );
+      setInfo(resp.connection);
+    } catch (e) {
+      setError(e instanceof Error ? e.message : String(e));
+    } finally {
+      setBusy(null);
+    }
+  }
+
+  return (
+    <div className="mx-3 mt-3 p-3 bg-surface-sunken/50 border border-line rounded">
+      <h3 className="text-xs text-ink-mid font-medium mb-1">External Connection</h3>
+      <p className="text-[10px] text-ink-soft mb-2">
+        This workspace runs an external agent. Use these controls to
+        re-show the setup snippets or rotate the workspace token.
+      </p>
+
+      <div className="flex gap-2 flex-wrap">
+        <button
+          type="button"
+          onClick={showConnection}
+          disabled={busy !== null}
+          className="px-3 py-1.5 bg-surface-card hover:bg-surface-card text-xs rounded text-ink-mid disabled:opacity-30 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60"
+        >
+          {busy === "show" ? "Loading…" : "Show connection info"}
+        </button>
+        <button
+          type="button"
+          onClick={() => setConfirmRotate(true)}
+          disabled={busy !== null}
+          className="px-3 py-1.5 bg-red-900/30 hover:bg-red-900/50 border border-red-800/60 text-xs rounded text-bad disabled:opacity-30 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-red-600/60"
+        >
+          {busy === "rotate" ? "Rotating…" : "Rotate credentials"}
+        </button>
+      </div>
+
+      {error && (
+        <div className="mt-2 px-2 py-1 bg-red-900/30 border border-red-800 rounded text-[10px] text-bad">
+          {error}
+        </div>
+      )}
+
+      <Dialog.Root open={confirmRotate} onOpenChange={setConfirmRotate}>
+        <Dialog.Portal>
+          <Dialog.Overlay className="fixed inset-0 bg-black/60 z-50" />
+          <Dialog.Content className="fixed left-1/2 top-1/2 z-50 w-[min(440px,92vw)] -translate-x-1/2 -translate-y-1/2 rounded-xl bg-surface-sunken border border-line p-5 shadow-2xl">
+            <Dialog.Title className="text-sm font-medium text-ink mb-2">
+              Rotate workspace credentials?
+            </Dialog.Title>
+            <Dialog.Description className="text-xs text-ink-mid mb-4 leading-relaxed">
+              This will mint a new <code className="font-mono">workspace_auth_token</code> and{' '}
+              <strong>immediately invalidate the current one</strong>. Your external
+              agent will start failing authentication on its next heartbeat
+              until you redeploy it with the new token.
+            </Dialog.Description>
+            <div className="flex justify-end gap-2">
+              <button
+                type="button"
+                onClick={() => setConfirmRotate(false)}
+                className="px-3 py-1.5 bg-surface-card text-xs rounded text-ink-mid"
+              >
+                Cancel
+              </button>
+              <button
+                type="button"
+                onClick={doRotate}
+                className="px-3 py-1.5 bg-red-700 hover:bg-red-600 text-xs rounded text-white"
+              >
+                Rotate
+              </button>
+            </div>
+          </Dialog.Content>
+        </Dialog.Portal>
+      </Dialog.Root>
+
+      <ExternalConnectModal info={info} onClose={() => setInfo(null)} />
+    </div>
+  );
+}
@@ -162,25 +162,29 @@ export function FilesTab({ workspaceId }: Props) {
      />

      {showDeleteAll && (
-        <div className="mx-3 mt-2 px-3 py-2 bg-red-950/30 border border-red-800/40 rounded space-y-1.5">
-          <p className="text-xs text-bad">Delete all {files.filter((f) => !f.dir).length} files? This cannot be undone.</p>
+        // role=alertdialog so SR users hear this destructive prompt
+        // 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">
+          <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-600 hover:bg-red-500 text-[10px] rounded text-white">Delete All</button>
-            <button type="button" onClick={() => setShowDeleteAll(false)} className="px-2 py-0.5 bg-surface-card hover:bg-surface-card text-[10px] rounded text-ink-mid">Cancel</button>
+            <button type="button" onClick={() => { handleDeleteAll(); setShowDeleteAll(false); }} className="px-2 py-0.5 bg-red-600 hover:bg-red-700 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>
+            <button type="button" onClick={() => setShowDeleteAll(false)} className="px-2 py-0.5 bg-surface-card hover:bg-surface-elevated hover:text-ink text-[10px] rounded text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-1 focus-visible:ring-offset-surface">Cancel</button>
          </div>
        </div>
      )}

      {error && (
-        <div className="mx-3 mt-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">{error}</div>
+        <div role="alert" className="mx-3 mt-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">{error}</div>
      )}

      {confirmDelete && (
-        <div className="mx-3 mt-2 px-3 py-2 bg-amber-950/30 border border-amber-800/40 rounded space-y-1.5">
-          <p 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 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">
+          <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-600 hover:bg-red-500 text-[10px] rounded text-white">Delete</button>
-            <button type="button" onClick={() => setConfirmDelete(null)} className="px-2 py-0.5 bg-surface-card hover:bg-surface-card text-[10px] rounded text-ink-mid">Cancel</button>
+            <button type="button" onClick={confirmDeleteFile} className="px-2 py-0.5 bg-red-600 hover:bg-red-700 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>
+            <button type="button" onClick={() => setConfirmDelete(null)} className="px-2 py-0.5 bg-surface-card hover:bg-surface-elevated hover:text-ink text-[10px] rounded text-ink-mid transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-1 focus-visible:ring-offset-surface">Cancel</button>
          </div>
        </div>
      )}
@@ -10,6 +10,7 @@ interface Props {
 interface MemoryEntry {
  key: string;
  value: unknown;
+  version?: number;
  expires_at: string | null;
  updated_at: string;
 }
@@ -28,6 +29,10 @@ export function MemoryTab({ workspaceId }: Props) {
  const [newValue, setNewValue] = useState("");
  const [newTTL, setNewTTL] = useState("");
  const [error, setError] = useState<string | null>(null);
+  const [editingKey, setEditingKey] = useState<string | null>(null);
+  const [editValue, setEditValue] = useState("");
+  const [editTTL, setEditTTL] = useState("");
+  const [editError, setEditError] = useState<string | null>(null);

  const awarenessUrl = useMemo(() => {
    try {
@@ -109,6 +114,69 @@ export function MemoryTab({ workspaceId }: Props) {
    }
  };

+  const beginEdit = (entry: MemoryEntry) => {
+    setEditError(null);
+    setEditingKey(entry.key);
+    // Stringify objects/arrays as pretty JSON; render plain strings raw so the
+    // editor doesn't surprise users with surrounding quotes.
+    setEditValue(
+      typeof entry.value === "string"
+        ? entry.value
+        : JSON.stringify(entry.value, null, 2),
+    );
+    if (entry.expires_at) {
+      const remainingMs = new Date(entry.expires_at).getTime() - Date.now();
+      const ttl = Math.max(0, Math.floor(remainingMs / 1000));
+      setEditTTL(ttl > 0 ? String(ttl) : "");
+    } else {
+      setEditTTL("");
+    }
+  };
+
+  const cancelEdit = () => {
+    setEditingKey(null);
+    setEditValue("");
+    setEditTTL("");
+    setEditError(null);
+  };
+
+  const handleEditSave = async (entry: MemoryEntry) => {
+    setEditError(null);
+
+    let parsedValue: unknown;
+    try {
+      parsedValue = JSON.parse(editValue);
+    } catch {
+      parsedValue = editValue;
+    }
+
+    // if_match_version closes the silent-overwrite hole when two writers
+    // race. The handler returns 409 with the current version on mismatch
+    // — surface that as a retry hint and reload to pick up the new state.
+    const body: Record<string, unknown> = { key: entry.key, value: parsedValue };
+    if (typeof entry.version === "number") {
+      body.if_match_version = entry.version;
+    }
+    if (editTTL) {
+      const ttl = parseInt(editTTL);
+      if (!Number.isNaN(ttl) && ttl > 0) body.ttl_seconds = ttl;
+    }
+
+    try {
+      await api.post(`/workspaces/${workspaceId}/memory`, body);
+      cancelEdit();
+      loadMemory();
+    } catch (e) {
+      const message = e instanceof Error ? e.message : "Failed to save";
+      if (message.includes("409") || /if_match_version mismatch/i.test(message)) {
+        setEditError("This entry changed since you opened it. Reloading.");
+        loadMemory();
+      } else {
+        setEditError(message);
+      }
+    }
+  };
+
  const openAwareness = () => {
    window.open(awarenessUrl, "_blank", "noopener,noreferrer");
  };
@@ -137,14 +205,14 @@ export function MemoryTab({ workspaceId }: Props) {
            <button
              type="button"
              onClick={() => setShowAwareness((prev) => !prev)}
-              className="shrink-0 px-2 py-1 bg-surface-card hover:bg-surface-card text-[10px] rounded text-ink"
+              className="shrink-0 px-2 py-1 bg-surface-card hover:bg-surface-elevated text-[10px] rounded text-ink"
            >
              {showAwareness ? "Collapse" : "Expand"}
            </button>
            <button
              type="button"
              onClick={openAwareness}
-              className="shrink-0 px-2 py-1 bg-surface-card hover:bg-surface-card text-[10px] rounded text-ink"
+              className="shrink-0 px-2 py-1 bg-surface-card hover:bg-surface-elevated text-[10px] rounded text-ink"
            >
              Open
            </button>
@@ -177,7 +245,7 @@ export function MemoryTab({ workspaceId }: Props) {
            <button
              type="button"
              onClick={() => setShowAwareness(true)}
-              className="shrink-0 px-2 py-1 bg-accent-strong hover:bg-accent text-[10px] rounded text-white"
+              className="shrink-0 px-2 py-1 bg-accent hover:bg-accent-strong text-[10px] rounded text-white"
            >
              Expand
            </button>
@@ -212,21 +280,21 @@ export function MemoryTab({ workspaceId }: Props) {
            <button
              type="button"
              onClick={() => setShowAdvanced((prev) => !prev)}
-              className="px-2 py-1 bg-surface-card hover:bg-surface-card text-[10px] rounded text-ink-mid"
+              className="px-2 py-1 bg-surface-card hover:bg-surface-elevated text-[10px] rounded text-ink-mid"
            >
              {showAdvanced ? "Hide Advanced" : "Advanced"}
            </button>
            <button
              type="button"
              onClick={loadMemory}
-              className="px-2 py-1 bg-surface-card hover:bg-surface-card text-[10px] rounded text-ink-mid"
+              className="px-2 py-1 bg-surface-card hover:bg-surface-elevated text-[10px] rounded text-ink-mid"
            >
              Refresh
            </button>
            <button
              type="button"
              onClick={() => { setShowAdd(!showAdd); if (!showAdd) setShowAdvanced(true); }}
-              className="px-2 py-1 bg-accent-strong hover:bg-accent text-[10px] rounded text-white"
+              className="px-2 py-1 bg-accent hover:bg-accent-strong text-[10px] rounded text-white"
            >
              + Add
            </button>
@@ -262,7 +330,7 @@ export function MemoryTab({ workspaceId }: Props) {
              <button
                type="button"
                onClick={handleAdd}
-                className="px-3 py-1 bg-accent-strong hover:bg-accent text-xs rounded text-white"
+                className="px-3 py-1 bg-accent hover:bg-accent-strong text-xs rounded text-white"
              >
                Save
              </button>
@@ -272,7 +340,7 @@ export function MemoryTab({ workspaceId }: Props) {
                  setShowAdd(false);
                  setError(null);
                }}
-                className="px-3 py-1 bg-surface-card hover:bg-surface-card text-xs rounded text-ink-mid"
+                className="px-3 py-1 bg-surface-card hover:bg-surface-elevated text-xs rounded text-ink-mid"
              >
                Cancel
              </button>
@@ -308,20 +376,71 @@ export function MemoryTab({ workspaceId }: Props) {

                  {expanded === entry.key && (
                    <div className="px-3 pb-2 space-y-2">
-                      <pre className="text-[10px] text-ink-mid bg-surface-sunken rounded p-2 overflow-x-auto max-h-40">
-                        {JSON.stringify(entry.value, null, 2)}
-                      </pre>
+                      {editingKey === entry.key ? (
+                        <div className="space-y-2">
+                          <textarea
+                            value={editValue}
+                            onChange={(e) => setEditValue(e.target.value)}
+                            rows={4}
+                            aria-label={`Edit value for ${entry.key}`}
+                            className="w-full bg-surface-sunken border border-line rounded px-2 py-1 text-xs font-mono text-ink focus:outline-none focus:border-accent resize-none"
+                          />
+                          <input
+                            value={editTTL}
+                            onChange={(e) => setEditTTL(e.target.value)}
+                            placeholder="TTL in seconds (blank = no expiry)"
+                            aria-label={`Edit TTL for ${entry.key}`}
+                            className="w-full bg-surface-sunken border border-line rounded px-2 py-1 text-xs text-ink focus:outline-none focus:border-accent"
+                          />
+                          {editError && (
+                            <div role="alert" className="text-[10px] text-bad">
+                              {editError}
+                            </div>
+                          )}
+                          <div className="flex gap-2">
+                            <button
+                              type="button"
+                              onClick={() => handleEditSave(entry)}
+                              className="px-3 py-1 bg-accent hover:bg-accent-strong text-xs rounded text-white"
+                            >
+                              Save
+                            </button>
+                            <button
+                              type="button"
+                              onClick={cancelEdit}
+                              className="px-3 py-1 bg-surface-card hover:bg-surface-elevated text-xs rounded text-ink-mid"
+                            >
+                              Cancel
+                            </button>
+                          </div>
+                        </div>
+                      ) : (
+                        <pre className="text-[10px] text-ink-mid bg-surface-sunken rounded p-2 overflow-x-auto max-h-40">
+                          {JSON.stringify(entry.value, null, 2)}
+                        </pre>
+                      )}
                      <div className="flex items-center justify-between">
                        <span className="text-[9px] text-ink-soft">
                          Updated: {new Date(entry.updated_at).toLocaleString()}
                        </span>
-                        <button
-                          type="button"
-                          onClick={() => handleDelete(entry.key)}
-                          className="text-[10px] text-bad hover:text-bad"
-                        >
-                          Delete
-                        </button>
+                        <div className="flex items-center gap-2">
+                          {editingKey !== entry.key && (
+                            <button
+                              type="button"
+                              onClick={() => beginEdit(entry)}
+                              className="text-[10px] text-ink-mid hover:bg-surface-elevated rounded px-1 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60"
+                            >
+                              Edit
+                            </button>
+                          )}
+                          <button
+                            type="button"
+                            onClick={() => handleDelete(entry.key)}
+                            className="text-[10px] text-bad hover:bg-red-950/40 rounded px-1 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-red-500/60"
+                          >
+                            Delete
+                          </button>
+                        </div>
                      </div>
                    </div>
                  )}
@@ -340,7 +459,7 @@ export function MemoryTab({ workspaceId }: Props) {
            <button
              type="button"
              onClick={() => setShowAdvanced(true)}
-              className="shrink-0 px-2 py-1 bg-accent-strong hover:bg-accent text-[10px] rounded text-white"
+              className="shrink-0 px-2 py-1 bg-accent hover:bg-accent-strong text-[10px] rounded text-white"
            >
              Show
            </button>
@@ -269,15 +269,23 @@ export function ScheduleTab({ workspaceId }: Props) {
          {error && <div className="text-[10px] text-bad">{error}</div>}
          <div className="flex gap-2">
            <button
+              type="button"
              onClick={handleSubmit}
              disabled={!formCron || !formPrompt}
-              className="text-[11px] px-3 py-1 bg-accent-strong text-white rounded hover:bg-accent disabled:opacity-40 transition-colors"
+              // Was bg-accent-strong hover:bg-accent — accent is the
+              // LIGHTER variant, so this hovered lighter on white text
+              // and dropped contrast below AA. Same trap fixed in
+              // OnboardingWizard, ConfirmDialog, ApprovalBanner.
+              className="text-[11px] px-3 py-1 bg-accent text-white rounded hover:bg-accent-strong disabled:opacity-40 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60 focus-visible:ring-offset-1 focus-visible:ring-offset-surface"
            >
              {editId ? "Update" : "Create"}
            </button>
            <button
+              type="button"
              onClick={resetForm}
-              className="text-[11px] px-3 py-1 bg-surface-card text-ink-mid rounded hover:bg-surface-card transition-colors"
+              // Was hover:bg-surface-card on top of bg-surface-card —
+              // silent no-op hover. Lift to surface-elevated.
+              className="text-[11px] px-3 py-1 bg-surface-card text-ink-mid rounded hover:bg-surface-elevated hover:text-ink transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/40 focus-visible:ring-offset-1 focus-visible:ring-offset-surface"
            >
              Cancel
            </button>
@@ -403,7 +403,7 @@ export function SkillsTab({ workspaceId, data }: Props) {
                  }}
                  placeholder="e.g. github://owner/repo#v1.0"
                  spellCheck={false}
-                  className="flex-1 rounded border border-line bg-surface px-2 py-1 text-[10px] text-ink placeholder:text-ink-soft focus:border-violet-600 focus:outline-none"
+                  className="flex-1 rounded border border-line bg-surface px-2 py-1 text-[10px] text-ink placeholder:text-ink-soft focus:outline-none focus:border-violet-600 focus-visible:ring-2 focus-visible:ring-violet-600/50"
                />
                <button
                  onClick={handleInstallCustom}
@@ -1,16 +1,105 @@
 "use client";

 import { useEffect, useRef, useState, useCallback } from "react";
+import type { WorkspaceNodeData } from "@/store/canvas";

 interface Props {
  workspaceId: string;
+  /** Workspace metadata from the canvas store. Optional for back-compat
+   *  with any caller that still mounts <TerminalTab workspaceId=... />
+   *  without threading data through (e.g. tests). When present, the
+   *  runtime field gates the early-return below. */
+  data?: WorkspaceNodeData;
 }

 import { deriveWsBaseUrl } from "@/lib/ws-url";

 const WS_URL = deriveWsBaseUrl();

-export function TerminalTab({ workspaceId }: Props) {
+/**
+ * NotAvailablePanel — full-tab placeholder with a big terminal-off icon
+ * for runtimes that don't expose a TTY (e.g. external workspaces, where
+ * the platform doesn't own the process). Pre-fix the tab tried to open
+ * a WebSocket against /ws/terminal/<id> for these workspaces, the server
+ * 404'd, and the user saw "Connection failed" — which reads as a bug,
+ * not as "this runtime intentionally has no shell". This banner makes
+ * the absence intentional.
+ */
+function NotAvailablePanel({ runtime }: { runtime: string }) {
+  return (
+    <div className="flex flex-col items-center justify-center h-full p-8 text-center bg-surface-sunken/30">
+      {/* Big terminal-off icon — bracket "[_]" with a slash through it.
+          Custom inline SVG so we don't depend on an icon set being
+          present at canvas build-time. */}
+      <svg
+        width="72"
+        height="72"
+        viewBox="0 0 72 72"
+        fill="none"
+        aria-hidden="true"
+        className="text-ink-soft mb-4"
+      >
+        <rect
+          x="10"
+          y="14"
+          width="52"
+          height="44"
+          rx="4"
+          stroke="currentColor"
+          strokeWidth="2.5"
+          fill="none"
+          opacity="0.6"
+        />
+        <path
+          d="M22 30 L30 36 L22 42"
+          stroke="currentColor"
+          strokeWidth="2.5"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          opacity="0.7"
+        />
+        <path
+          d="M34 44 L44 44"
+          stroke="currentColor"
+          strokeWidth="2.5"
+          strokeLinecap="round"
+          opacity="0.7"
+        />
+        {/* Diagonal cancel slash */}
+        <path
+          d="M14 14 L58 58"
+          stroke="currentColor"
+          strokeWidth="3"
+          strokeLinecap="round"
+        />
+      </svg>
+      <h3 className="text-sm font-medium text-ink mb-1.5">Terminal not available</h3>
+      <p className="text-[11px] text-ink-soft max-w-xs leading-relaxed">
+        This workspace runs the{" "}
+        <span className="font-mono text-ink-mid">{runtime}</span> runtime,
+        which doesn't expose a shell. Use the Chat tab to interact with the
+        agent directly.
+      </p>
+    </div>
+  );
+}
+
+/** Runtimes that don't expose a TTY. Keep narrow — only add a runtime
+ *  here when its provisioner genuinely has no shell endpoint, otherwise
+ *  the user loses access to a real debugging surface. */
+const RUNTIMES_WITHOUT_TERMINAL = new Set(["external"]);
+
+export function TerminalTab({ workspaceId, data }: Props) {
+  // Early-return for runtimes that have no shell. Skips the entire
+  // xterm + WebSocket dance below — without this, mounting the tab
+  // for an external workspace pops the WS, gets a 404 from the
+  // workspace-server (no /ws/terminal/<id> route registered for it),
+  // and shows "Connection failed" with a Reconnect button — confusing
+  // because the workspace IS healthy, just doesn't have a TTY.
+  if (data && RUNTIMES_WITHOUT_TERMINAL.has(data.runtime)) {
+    return <NotAvailablePanel runtime={data.runtime} />;
+  }
+
  const containerRef = useRef<HTMLDivElement>(null);
  const termRef = useRef<{ dispose: () => void } | null>(null);
  const wsRef = useRef<WebSocket | null>(null);
@@ -123,15 +212,18 @@ export function TerminalTab({ workspaceId }: Props) {

  return (
    <div className="flex flex-col h-full">
-      {/* Status bar — role="status" so connection state changes are announced politely */}
+      {/* Status bar — role="status" so connection state changes are announced politely.
+          Terminal body stays dark unconditionally (Canvas v4 design rule), but the
+          chrome wrapping it now uses semantic status colors so the dot/text stay
+          readable in both themes. */}
      <div role="status" aria-live="polite" className="flex items-center justify-between px-3 py-1.5 border-b border-zinc-700 bg-zinc-800/50">
        <div className="flex items-center gap-2">
          <div className={`w-2 h-2 rounded-full ${
-            status === "connected" ? "bg-green-500" :
-            status === "connecting" ? "bg-yellow-500 motion-safe:animate-pulse" :
-            status === "error" ? "bg-red-500" : "bg-zinc-500"
+            status === "connected" ? "bg-good" :
+            status === "connecting" ? "bg-warm motion-safe:animate-pulse" :
+            status === "error" ? "bg-bad" : "bg-ink-soft"
          }`} />
-          <span className="text-[10px] text-zinc-400">
+          <span className="text-[10px] text-zinc-300">
            {status === "connected" ? "Shell active" :
             status === "connecting" ? "Connecting..." :
             status === "error" ? "Connection failed" : "Disconnected"}
@@ -139,8 +231,13 @@ export function TerminalTab({ workspaceId }: Props) {
        </div>
        {(status === "disconnected" || status === "error") && (
          <button
+            type="button"
            onClick={reconnect}
-            className="text-[10px] text-blue-400 hover:text-blue-300"
+            // Accent over hardcoded blue. text-accent + hover-strong stays
+            // readable on the dark terminal chrome and matches the rest
+            // of the canvas semantic palette. Focus-visible ring added so
+            // keyboard users see where focus lands on a recovery button.
+            className="text-[10px] text-accent hover:text-accent-strong rounded-sm px-1 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/60"
          >
            Reconnect
          </button>
@@ -149,7 +246,7 @@ export function TerminalTab({ workspaceId }: Props) {

      {/* Error message — role="alert" announces immediately via assertive live region */}
      {errorMsg && (
-        <div role="alert" className="mx-3 mt-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-red-400">
+        <div role="alert" className="mx-3 mt-2 px-3 py-1.5 bg-red-900/30 border border-red-800 rounded text-xs text-bad">
          {errorMsg}
        </div>
      )}
@@ -55,7 +55,13 @@ export function TracesTab({ workspaceId }: Props) {
    <div className="p-4 space-y-2">
      <div className="flex items-center justify-between mb-2">
        <span className="text-xs text-ink-mid">{traces.length} traces</span>
-        <button type="button" onClick={loadTraces} className="text-[10px] text-ink-soft hover:text-ink-mid">
+        <button
+          type="button"
+          onClick={loadTraces}
+          // Added focus-visible ring; previous version was hover-only,
+          // invisible to keyboard users.
+          className="text-[10px] text-ink-soft hover:text-ink-mid rounded-sm px-1 transition-colors focus:outline-none focus-visible:ring-2 focus-visible:ring-accent/50"
+        >
          Refresh
        </button>
      </div>
@@ -79,66 +85,79 @@ export function TracesTab({ workspaceId }: Props) {
        </div>
      ) : (
        <div className="space-y-1">
-          {traces.map((trace) => (
-            <div key={trace.id} className="bg-surface-card/40 border border-line/40 rounded-lg overflow-hidden">
-              <button
-                onClick={() => setExpanded(expanded === trace.id ? null : trace.id)}
-                className="w-full px-3 py-2 flex items-center gap-2 text-left hover:bg-surface-card/60 transition-colors"
-              >
-                <div className={`w-1.5 h-1.5 rounded-full shrink-0 ${
-                  trace.status === "ERROR" ? "bg-red-400" : "bg-emerald-400"
-                }`} />
-                <div className="flex-1 min-w-0">
-                  <div className="text-[11px] text-ink truncate">{trace.name || "trace"}</div>
-                  <div className="text-[9px] text-ink-soft">{formatTime(trace.timestamp)}</div>
-                </div>
-                <div className="flex items-center gap-2 shrink-0">
-                  {trace.latency != null && (
-                    <span className="text-[9px] text-ink-soft tabular-nums">
-                      {trace.latency > 1000 ? `${(trace.latency / 1000).toFixed(1)}s` : `${trace.latency}ms`}
-                    </span>
-                  )}
-                  {trace.usage?.total != null && (
-                    <span className="text-[9px] text-ink-soft tabular-nums">
-                      {trace.usage.total} tok
-                    </span>
-                  )}
-                  <span className="text-[9px] text-ink-soft">
-                    {expanded === trace.id ? "▼" : "▶"}
-                  </span>
-                </div>
-              </button>
-
-              {expanded === trace.id && (
-                <div className="px-3 pb-2 space-y-2 border-t border-line/30">
-                  {trace.input && (
-                    <div>
-                      <div className="text-[9px] text-ink-soft uppercase tracking-wider mt-2 mb-1">Input</div>
-                      <pre className="text-[9px] text-ink-mid bg-surface-sunken rounded p-2 overflow-x-auto max-h-32">
-                        {String(typeof trace.input === "string" ? trace.input : JSON.stringify(trace.input, null, 2))}
-                      </pre>
-                    </div>
-                  )}
-                  {trace.output && (
-                    <div>
-                      <div className="text-[9px] text-ink-soft uppercase tracking-wider mb-1">Output</div>
-                      <pre className="text-[9px] text-ink-mid bg-surface-sunken rounded p-2 overflow-x-auto max-h-32">
-                        {String(typeof trace.output === "string" ? trace.output : JSON.stringify(trace.output, null, 2))}
-                      </pre>
-                    </div>
-                  )}
-                  {trace.totalCost != null && (
-                    <div className="text-[9px] text-ink-soft">
-                      Cost: ${trace.totalCost.toFixed(6)}
-                    </div>
-                  )}
-                  <div className="text-[8px] text-ink-soft font-mono select-all">
-                    {trace.id}
+          {traces.map((trace) => {
+            const isOpen = expanded === trace.id;
+            const panelId = `trace-detail-${trace.id}`;
+            return (
+              <div key={trace.id} className="bg-surface-card/40 border border-line/40 rounded-lg overflow-hidden">
+                <button
+                  type="button"
+                  onClick={() => setExpanded(isOpen ? null : trace.id)}
+                  // aria-expanded + aria-controls so SR announces the
+                  // open/closed state and links the row to its detail
+                  // panel. Same pattern shipped on EventsTab.
+                  aria-expanded={isOpen}
+                  aria-controls={panelId}
+                  className="w-full px-3 py-2 flex items-center gap-2 text-left hover:bg-surface-card/60 focus:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-accent/50 transition-colors"
+                >
+                  {/* Status dot uses semantic bad/good tokens — was hardcoded
+                      bg-red-400 / bg-emerald-400 which doesn't pin to the
+                      canvas-wide ramp. */}
+                  <div className={`w-1.5 h-1.5 rounded-full shrink-0 ${
+                    trace.status === "ERROR" ? "bg-bad" : "bg-good"
+                  }`} />
+                  <div className="flex-1 min-w-0">
+                    <div className="text-[11px] text-ink truncate">{trace.name || "trace"}</div>
+                    <div className="text-[9px] text-ink-soft">{formatTime(trace.timestamp)}</div>
                  </div>
-                </div>
-              )}
-            </div>
-          ))}
+                  <div className="flex items-center gap-2 shrink-0">
+                    {trace.latency != null && (
+                      <span className="text-[9px] text-ink-soft tabular-nums">
+                        {trace.latency > 1000 ? `${(trace.latency / 1000).toFixed(1)}s` : `${trace.latency}ms`}
+                      </span>
+                    )}
+                    {trace.usage?.total != null && (
+                      <span className="text-[9px] text-ink-soft tabular-nums">
+                        {trace.usage.total} tok
+                      </span>
+                    )}
+                    <span aria-hidden="true" className="text-[9px] text-ink-soft">
+                      {isOpen ? "▼" : "▶"}
+                    </span>
+                  </div>
+                </button>
+
+                {isOpen && (
+                  <div id={panelId} className="px-3 pb-2 space-y-2 border-t border-line/30">
+                    {trace.input && (
+                      <div>
+                        <div className="text-[9px] text-ink-soft uppercase tracking-wider mt-2 mb-1">Input</div>
+                        <pre className="text-[9px] text-ink-mid bg-surface-sunken rounded p-2 overflow-x-auto max-h-32">
+                          {String(typeof trace.input === "string" ? trace.input : JSON.stringify(trace.input, null, 2))}
+                        </pre>
+                      </div>
+                    )}
+                    {trace.output && (
+                      <div>
+                        <div className="text-[9px] text-ink-soft uppercase tracking-wider mb-1">Output</div>
+                        <pre className="text-[9px] text-ink-mid bg-surface-sunken rounded p-2 overflow-x-auto max-h-32">
+                          {String(typeof trace.output === "string" ? trace.output : JSON.stringify(trace.output, null, 2))}
+                        </pre>
+                      </div>
+                    )}
+                    {trace.totalCost != null && (
+                      <div className="text-[9px] text-ink-soft">
+                        Cost: ${trace.totalCost.toFixed(6)}
+                      </div>
+                    )}
+                    <div className="text-[8px] text-ink-soft font-mono select-all">
+                      {trace.id}
+                    </div>
+                  </div>
+                )}
+              </div>
+            );
+          })}
        </div>
      )}
    </div>
@@ -0,0 +1,340 @@
+// @vitest-environment jsdom
+//
+// Pins the lazy-loading chat-history pagination added 2026-05-05.
+//
+// Pre-fix: ChatTab fetched the newest 50 messages on every mount and
+// scrolled to bottom, paying full DOM cost up-front even when the user
+// only wanted to read the last few bubbles. Post-fix: initial load is
+// bounded to 10 newest, and an IntersectionObserver on a top sentinel
+// triggers loadOlder() (batch of 20 with `before_ts` cursor) when the
+// user scrolls up.
+//
+// Pinned branches:
+//   1. Initial fetch carries `limit=10` and NO before_ts (newest-first
+//      slice). Pre-fix this was limit=50.
+//   2. Server returning fewer than `limit` rows clears `hasMore` so the
+//      top sentinel is removed and the IO observer disconnects — no
+//      "Loading older messages…" spinner on a short conversation.
+//   3. Server returning exactly `limit` rows on the first batch keeps
+//      hasMore=true so the sentinel mounts (verified indirectly by
+//      asserting the rendered bubble count matches the full page).
+//   4. The retry button after a failed initial load uses the same
+//      INITIAL_HISTORY_LIMIT (10), not the legacy 50.
+//
+// IntersectionObserver / scroll-anchor restoration is exercised by the
+// E2E synth-canary suite — pinning it in jsdom would require mocking
+// the observer and faking layout, which is brittler than trusting a
+// live-DOM canary against the staging tenant.
+
+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);
+
+// Both ChatTab sub-panels (MyChat + AgentComms) mount simultaneously so
+// keyboard tab order and aria-controls land on a real DOM. Both fire
+// /activity GETs on mount: MyChat's hits `type=a2a_receive&source=canvas`,
+// AgentComms's hits a different filter. Route the mock by URL so each
+// gets a sensible default and only MyChat's call is what the assertions
+// scrutinise.
+const myChatActivityCalls: string[] = [];
+let myChatNextResponse: { ok: true; rows: unknown[] } | { ok: false; err: Error } = {
+  ok: true,
+  rows: [],
+};
+const apiGet = vi.fn((path: string): Promise<unknown> => {
+  if (path.includes("type=a2a_receive") && path.includes("source=canvas")) {
+    myChatActivityCalls.push(path);
+    if (myChatNextResponse.ok) return Promise.resolve(myChatNextResponse.rows);
+    return Promise.reject(myChatNextResponse.err);
+  }
+  // AgentComms / heartbeat / anything else — empty array is a safe
+  // default that won't blow up the corresponding component's .then().
+  return Promise.resolve([]);
+});
+const apiPost = vi.fn();
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: (path: string) => apiGet(path),
+    post: (path: string, body: unknown) => apiPost(path, body),
+    del: vi.fn(),
+    patch: vi.fn(),
+    put: vi.fn(),
+  },
+}));
+
+vi.mock("@/store/canvas", () => ({
+  useCanvasStore: vi.fn((selector?: (s: unknown) => unknown) =>
+    selector ? selector({ agentMessages: {}, consumeAgentMessages: () => [] }) : {},
+  ),
+}));
+
+// Capture IntersectionObserver instances so tests can drive callbacks
+// directly (jsdom has no layout, so nothing crosses thresholds on its
+// own) AND assert observer-instance count to pin the perf invariant
+// that live-message churn doesn't tear down + re-arm the observer.
+type IOInstance = {
+  callback: IntersectionObserverCallback;
+  observed: Element[];
+  disconnected: boolean;
+};
+const ioInstances: IOInstance[] = [];
+
+beforeEach(() => {
+  apiGet.mockClear();
+  apiPost.mockReset();
+  myChatActivityCalls.length = 0;
+  myChatNextResponse = { ok: true, rows: [] };
+  ioInstances.length = 0;
+  class FakeIO {
+    private inst: IOInstance;
+    constructor(cb: IntersectionObserverCallback) {
+      this.inst = { callback: cb, observed: [], disconnected: false };
+      ioInstances.push(this.inst);
+    }
+    observe(el: Element) {
+      this.inst.observed.push(el);
+    }
+    unobserve() {}
+    disconnect() {
+      this.inst.disconnected = true;
+    }
+  }
+  // Install on every reachable global — different bundlers / module
+  // graphs can resolve `IntersectionObserver` via `window`, `globalThis`,
+  // or the bare global. Without all three, jsdom's own (pre-existing)
+  // stub silently wins and ioInstances stays empty.
+  (window as unknown as { IntersectionObserver: unknown }).IntersectionObserver = FakeIO;
+  (globalThis as unknown as { IntersectionObserver: unknown }).IntersectionObserver = FakeIO;
+  // jsdom doesn't implement scrollIntoView; ChatTab calls it after every
+  // messages update.
+  Element.prototype.scrollIntoView = vi.fn();
+});
+
+function triggerIntersection(instanceIdx = -1) {
+  // -1 → the latest observer (the live one). Tests targeting an old
+  // (disconnected) instance pass a positive index.
+  const inst = ioInstances.at(instanceIdx);
+  if (!inst) throw new Error(`no IO instance at ${instanceIdx}`);
+  inst.callback(
+    [{ isIntersecting: true, target: inst.observed[0] } as IntersectionObserverEntry],
+    inst as unknown as IntersectionObserver,
+  );
+}
+
+import { ChatTab } from "../ChatTab";
+
+function makeActivityRow(seq: number): Record<string, unknown> {
+  // Zero-pad seq into the minute slot so "seq=10" doesn't produce
+  // the invalid timestamp "00:010:00Z" (caught by the loadOlder URL
+  // assertion below — first version of the helper used `0${seq}` and
+  // the test failed on `before_ts` having an extra digit).
+  const mm = String(seq).padStart(2, "0");
+  return {
+    activity_type: "a2a_receive",
+    status: "ok",
+    created_at: `2026-05-05T00:${mm}:00Z`,
+    request_body: { params: { message: { parts: [{ kind: "text", text: `user msg ${seq}` }] } } },
+    response_body: { result: `agent reply ${seq}` },
+  };
+}
+
+// Server returns newest-first; the helper builds a server-shape page
+// so the order in the rendered messages array matches production.
+function newestFirstPage(start: number, count: number): unknown[] {
+  return Array.from({ length: count }, (_, i) => makeActivityRow(start + count - 1 - i));
+}
+
+const minimalData = {
+  status: "online" as const,
+  runtime: "claude-code",
+  currentTask: null,
+} as unknown as Parameters<typeof ChatTab>[0]["data"];
+
+describe("ChatTab lazy history pagination", () => {
+  it("initial fetch carries limit=10 (not the legacy 50)", async () => {
+    myChatNextResponse = { ok: true, rows: [makeActivityRow(1)] };
+    render(<ChatTab workspaceId="ws-1" data={minimalData} />);
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(1));
+    const url = myChatActivityCalls[0];
+    expect(url).toContain("limit=10");
+    expect(url).not.toContain("limit=50");
+    // before_ts should NOT be set on the initial fetch — that's the
+    // newest-first slice the user lands on.
+    expect(url).not.toContain("before_ts");
+  });
+
+  it("hides the top sentinel when initial fetch returns fewer than the limit", async () => {
+    // 3 < 10 → server says "no more older history exists"; sentinel
+    // should NOT mount and the "Loading older messages…" line should
+    // never appear (it can't, since the sentinel is what triggers it).
+    myChatNextResponse = {
+      ok: true,
+      rows: [makeActivityRow(1), makeActivityRow(2), makeActivityRow(3)],
+    };
+    render(<ChatTab workspaceId="ws-2" data={minimalData} />);
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(1));
+    await waitFor(() => {
+      expect(screen.queryByText(/Loading chat history/i)).toBeNull();
+    });
+    expect(screen.queryByText(/Loading older messages/i)).toBeNull();
+  });
+
+  it("renders all messages when initial fetch returns exactly the limit", async () => {
+    // 10 == limit → server might have more older rows; sentinel SHOULD
+    // mount so the IO observer can fire loadOlder() on scroll-up. We
+    // verify by checking the rendered bubble count — if hasMore stayed
+    // true the sentinel render path doesn't crash and all 10 rows
+    // produced their pair of bubbles.
+    const fullPage = Array.from({ length: 10 }, (_, i) => makeActivityRow(i + 1));
+    myChatNextResponse = { ok: true, rows: fullPage };
+    render(<ChatTab workspaceId="ws-3" data={minimalData} />);
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(1));
+    await waitFor(() => {
+      expect(screen.queryByText(/Loading chat history/i)).toBeNull();
+    });
+    expect(screen.getAllByText(/user msg/).length).toBe(10);
+    expect(screen.getAllByText(/agent reply/).length).toBe(10);
+  });
+
+  it("retry-after-failure uses limit=10, not the legacy 50", async () => {
+    myChatNextResponse = { ok: false, err: new Error("network down") };
+    render(<ChatTab workspaceId="ws-4" data={minimalData} />);
+    const retry = await screen.findByText(/Retry/);
+    myChatNextResponse = { ok: true, rows: [makeActivityRow(1)] };
+    fireEvent.click(retry);
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(2));
+    const retryUrl = myChatActivityCalls[1];
+    expect(retryUrl).toContain("limit=10");
+    expect(retryUrl).not.toContain("limit=50");
+  });
+
+  it("loadOlder fetches limit=20 with before_ts=oldest.timestamp", async () => {
+    // Initial page = 10 rows in newest-first order (seq 10..1). After
+    // the component reverses to oldest-first for display, messages[0]
+    // is built from seq=1 — the oldest — and its timestamp is what
+    // before_ts should carry.
+    myChatNextResponse = { ok: true, rows: newestFirstPage(1, 10) };
+    render(<ChatTab workspaceId="ws-load-older" data={minimalData} />);
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(1));
+    await waitFor(() => expect(ioInstances.length).toBeGreaterThan(0));
+
+    // Stage the older-batch response, then fire the IO callback.
+    myChatNextResponse = { ok: true, rows: newestFirstPage(0, 1) };
+    triggerIntersection();
+
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(2));
+    const olderUrl = myChatActivityCalls[1];
+    expect(olderUrl).toContain("limit=20");
+    expect(olderUrl).toContain("before_ts=");
+    expect(decodeURIComponent(olderUrl)).toContain("before_ts=2026-05-05T00:01:00Z");
+  });
+
+  it("inflight guard rejects a second IO trigger while first loadOlder is in flight", async () => {
+    myChatNextResponse = { ok: true, rows: newestFirstPage(1, 10) };
+    render(<ChatTab workspaceId="ws-inflight" data={minimalData} />);
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(1));
+    await waitFor(() => expect(ioInstances.length).toBeGreaterThan(0));
+
+    // Hold the next loadOlder fetch open with a manual deferred so we
+    // can fire the second trigger while the first is in-flight.
+    let release!: (rows: unknown[]) => void;
+    const deferred = new Promise<unknown[]>((res) => {
+      release = res;
+    });
+    apiGet.mockImplementationOnce((path: string): Promise<unknown> => {
+      myChatActivityCalls.push(path);
+      return deferred;
+    });
+
+    triggerIntersection(); // start loadOlder #1
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(2));
+
+    // Second IO trigger lands while #1 is still pending.
+    triggerIntersection();
+    triggerIntersection();
+    triggerIntersection();
+    // Without the inflight guard, each of these would have started a
+    // new fetch. With the guard, none of them do — call count stays 2.
+    await new Promise((r) => setTimeout(r, 10));
+    expect(myChatActivityCalls.length).toBe(2);
+
+    // Release the first fetch. Inflight clears in the finally block;
+    // a subsequent IO trigger is permitted again (verified by checking
+    // we can fire a follow-up after release without hanging the test).
+    release([]);
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(2));
+  });
+
+  it("empty older response clears the scroll anchor and unmounts the sentinel", async () => {
+    // The bug we're pinning: if loadOlder returns 0 rows, the
+    // scrollAnchorRef must be cleared so the next paint doesn't try to
+    // restore against a no-op prepend (which would fight the natural
+    // bottom-pin for any subsequent live message). hasMore flipping to
+    // false is the same flag-flip path; sentinel disappearing is the
+    // observable proxy.
+    myChatNextResponse = { ok: true, rows: newestFirstPage(1, 10) };
+    render(<ChatTab workspaceId="ws-anchor" data={minimalData} />);
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(1));
+    await waitFor(() => expect(ioInstances.length).toBeGreaterThan(0));
+
+    myChatNextResponse = { ok: true, rows: [] }; // empty → reachedEnd
+    triggerIntersection();
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(2));
+
+    // After reachedEnd the sentinel unmounts (hasMore=false). We can't
+    // peek scrollAnchorRef directly, but we can assert the consequence:
+    // scrollIntoView (the bottom-pin for live appends) is not blocked
+    // by a stale anchor. Trigger a re-render via an unrelated state
+    // change… in practice the safest assertion here is that the
+    // sentinel disappeared (proving the empty response propagated to
+    // hasMore correctly, which is the same flag-flip path as anchor
+    // clearing).
+    await waitFor(() => {
+      expect(screen.queryByText(/Loading older messages/i)).toBeNull();
+    });
+  });
+
+  it("IntersectionObserver does not churn when older messages prepend", async () => {
+    // Whole-PR perf invariant: prepending older history (the load-bearing
+    // user gesture) must NOT tear down + re-arm the IO observer.
+    // Triggering loadOlder is the cleanest way to drive a messages
+    // mutation from inside the test, since live agent push goes through
+    // a Zustand store that's harder to drive reliably from jsdom.
+    //
+    // Pre-fix, loadOlder depended on `messages`, so every prepend
+    // recreated loadOlder → re-ran the IO effect → new observer. Each
+    // call to triggerIntersection() produced a fresh disconnected
+    // observer + a new live one. Post-fix, the observer survives.
+    myChatNextResponse = { ok: true, rows: newestFirstPage(1, 10) };
+    render(<ChatTab workspaceId="ws-stable-io" data={minimalData} />);
+    await waitFor(() => expect(myChatActivityCalls.length).toBe(1));
+    await waitFor(() => expect(ioInstances.length).toBeGreaterThan(0));
+
+    // Snapshot the observer instance after first paint stabilises.
+    const observerBefore = ioInstances.at(-1);
+    expect(observerBefore).toBeDefined();
+    expect(observerBefore!.disconnected).toBe(false);
+
+    // Trigger three older-batch prepends. Each batch returns the full
+    // OLDER_HISTORY_BATCH (20 rows) so reachedEnd stays false and the
+    // sentinel keeps mounting. Pre-fix, each prepend mutated `messages`
+    // → recreated loadOlder → re-ran the IO effect → new observer.
+    for (let batch = 0; batch < 3; batch++) {
+      myChatNextResponse = {
+        ok: true,
+        rows: newestFirstPage(-(batch + 1) * 20, 20),
+      };
+      const callsBefore = myChatActivityCalls.length;
+      triggerIntersection();
+      await waitFor(() =>
+        expect(myChatActivityCalls.length).toBe(callsBefore + 1),
+      );
+    }
+
+    // The original observer is still the live one — no churn.
+    expect(observerBefore!.disconnected).toBe(false);
+    expect(ioInstances.at(-1)).toBe(observerBefore);
+  });
+});
@@ -0,0 +1,125 @@
+// @vitest-environment jsdom
+//
+// Regression tests for the ConfigTab section restructure (user feedback
+// 2026-05-04: "Skills and Tools are having their own tab as plugin, and
+// Prompt Files are in the file system which can be directly edited. Am
+// I missing something?" + "Tools should be merged into plugin then, and
+// for prompt files... should be in another section than in skill& tools").
+//
+// What this pins:
+//   1. The "Skills & Tools" section title is gone.
+//   2. Editable Skills + Tools tag inputs are gone (managed elsewhere).
+//   3. A dedicated "Prompt Files" section exists with explanatory text.
+//
+// If a future PR re-adds the Skills/Tools tag inputs to ConfigTab, this
+// suite catches it.
+
+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();
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: (path: string) => apiGet(path),
+    patch: vi.fn(),
+    put: vi.fn(),
+    post: vi.fn(),
+    del: vi.fn(),
+  },
+}));
+
+const storeUpdateNodeData = vi.fn();
+const storeRestartWorkspace = vi.fn();
+vi.mock("@/store/canvas", () => ({
+  useCanvasStore: Object.assign(
+    (selector: (s: unknown) => unknown) =>
+      selector({ restartWorkspace: storeRestartWorkspace, updateNodeData: storeUpdateNodeData }),
+    {
+      getState: () => ({
+        restartWorkspace: storeRestartWorkspace,
+        updateNodeData: storeUpdateNodeData,
+      }),
+    },
+  ),
+}));
+
+vi.mock("../AgentCardSection", () => ({
+  AgentCardSection: () => <div data-testid="agent-card-stub" />,
+}));
+
+import { ConfigTab } from "../ConfigTab";
+
+beforeEach(() => {
+  apiGet.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 section restructure", () => {
+  it("does not render a 'Skills & Tools' section title", async () => {
+    render(<ConfigTab workspaceId="ws-test" />);
+    await waitFor(() => expect(apiGet).toHaveBeenCalled());
+    // Section button uses the title as its accessible name; should be absent.
+    expect(screen.queryByRole("button", { name: /Skills\s*&\s*Tools/i })).toBeNull();
+  });
+
+  it("does not render an editable Skills tag input", async () => {
+    render(<ConfigTab workspaceId="ws-test" />);
+    await waitFor(() => expect(apiGet).toHaveBeenCalled());
+    // TagList renders its label; check no input labelled "Skills" in the form.
+    // (Skills are managed via the dedicated Skills tab.)
+    const skillsLabels = screen
+      .queryAllByText(/^Skills$/)
+      .filter((el) => el.tagName.toLowerCase() === "label");
+    expect(skillsLabels).toHaveLength(0);
+  });
+
+  it("does not render an editable Tools tag input", async () => {
+    render(<ConfigTab workspaceId="ws-test" />);
+    await waitFor(() => expect(apiGet).toHaveBeenCalled());
+    // Tools are managed via the Plugins tab — install a plugin → its tools
+    // become available. No reason to type tool names here.
+    const toolsLabels = screen
+      .queryAllByText(/^Tools$/)
+      .filter((el) => el.tagName.toLowerCase() === "label");
+    expect(toolsLabels).toHaveLength(0);
+  });
+
+  it("renders a dedicated 'Prompt Files' section with explanatory copy", async () => {
+    render(<ConfigTab workspaceId="ws-test" />);
+    await waitFor(() => expect(apiGet).toHaveBeenCalled());
+    // Section is collapsed by default — find + expand first.
+    const sectionButton = screen.getByRole("button", { name: /Prompt Files/i });
+    expect(sectionButton).toBeTruthy();
+    fireEvent.click(sectionButton);
+    // Explanatory copy mentions system-prompt.md (split across <code> tags
+    // so use textContent on any element rather than the default text matcher).
+    await waitFor(() => {
+      const matches = screen.queryAllByText((_, el) =>
+        (el?.textContent || "").includes("system-prompt.md"),
+      );
+      expect(matches.length).toBeGreaterThan(0);
+    });
+  });
+});
@@ -0,0 +1,156 @@
+// @vitest-environment jsdom
+//
+// ExternalConnectionSection — coverage for the credential-rotate +
+// re-show-instructions UI on the Config tab.
+//
+// What this pins:
+//   1. "Show connection info" → GET /external/connection, opens modal
+//      with auth_token=""
+//   2. "Rotate credentials" → confirm dialog → POST /external/rotate,
+//      opens modal with the returned auth_token
+//   3. Confirm dialog cancels without firing the POST
+//   4. API failure surfaces an error chip (no silent loss)
+
+import { describe, it, expect, vi, afterEach, beforeEach } from "vitest";
+import {
+  render,
+  screen,
+  cleanup,
+  fireEvent,
+  waitFor,
+} from "@testing-library/react";
+import React from "react";
+
+afterEach(cleanup);
+
+const apiGet = vi.fn();
+const apiPost = vi.fn();
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: (path: string) => apiGet(path),
+    post: (path: string, body?: unknown) => apiPost(path, body),
+    patch: vi.fn(),
+    put: vi.fn(),
+    del: vi.fn(),
+  },
+}));
+
+import { ExternalConnectionSection } from "../ExternalConnectionSection";
+
+beforeEach(() => {
+  apiGet.mockReset();
+  apiPost.mockReset();
+});
+
+const SAMPLE_INFO = {
+  workspace_id: "ws-test",
+  platform_url: "https://platform.example.test",
+  auth_token: "",
+  registry_endpoint: "https://platform.example.test/registry/register",
+  heartbeat_endpoint: "https://platform.example.test/registry/heartbeat",
+  // The modal stamps these snippets server-side; for the test we
+  // bake workspace_id into one so the rendered DOM contains a
+  // findable token after the modal mounts.
+  curl_register_template: "# curl ws=ws-test",
+  python_snippet: "# py ws=ws-test",
+  claude_code_channel_snippet: "# claude ws=ws-test",
+  universal_mcp_snippet: "# mcp ws=ws-test",
+  hermes_channel_snippet: "# hermes ws=ws-test",
+  codex_snippet: "# codex ws=ws-test",
+  openclaw_snippet: "# openclaw ws=ws-test",
+};
+
+describe("ExternalConnectionSection", () => {
+  it("renders both action buttons", () => {
+    render(<ExternalConnectionSection workspaceId="ws-test" />);
+    expect(screen.getByRole("button", { name: /show connection info/i })).toBeTruthy();
+    expect(screen.getByRole("button", { name: /rotate credentials/i })).toBeTruthy();
+  });
+
+  it("'Show connection info' calls GET /external/connection and opens modal with blank token", async () => {
+    apiGet.mockResolvedValue({ connection: { ...SAMPLE_INFO, auth_token: "" } });
+    render(<ExternalConnectionSection workspaceId="ws-test" />);
+
+    fireEvent.click(screen.getByRole("button", { name: /show connection info/i }));
+
+    await waitFor(() =>
+      expect(apiGet).toHaveBeenCalledWith("/workspaces/ws-test/external/connection"),
+    );
+    // The ExternalConnectModal renders the workspace_id field in its
+    // copy-block. document.body covers Radix's portal mount point.
+    await waitFor(() => {
+      expect(document.body.textContent || "").toContain("ws-test");
+    });
+  });
+
+  it("'Rotate credentials' opens confirm dialog before firing POST", async () => {
+    render(<ExternalConnectionSection workspaceId="ws-test" />);
+    fireEvent.click(screen.getByRole("button", { name: /rotate credentials/i }));
+
+    // Confirm dialog appears with the destructive copy.
+    await waitFor(() => {
+      expect(
+        screen.getByText(/Rotate workspace credentials\?/i),
+      ).toBeTruthy();
+    });
+    expect(screen.getByText(/immediately invalidate the current one/i)).toBeTruthy();
+
+    // POST must NOT have fired yet — only on confirm.
+    expect(apiPost).not.toHaveBeenCalled();
+  });
+
+  it("Cancel in confirm dialog dismisses without rotating", async () => {
+    render(<ExternalConnectionSection workspaceId="ws-test" />);
+    fireEvent.click(screen.getByRole("button", { name: /rotate credentials/i }));
+
+    await waitFor(() =>
+      expect(screen.getByText(/Rotate workspace credentials\?/i)).toBeTruthy(),
+    );
+    fireEvent.click(screen.getByRole("button", { name: /^cancel$/i }));
+
+    await waitFor(() =>
+      expect(screen.queryByText(/Rotate workspace credentials\?/i)).toBeNull(),
+    );
+    expect(apiPost).not.toHaveBeenCalled();
+  });
+
+  it("Confirm in dialog POSTs to /external/rotate and opens modal with returned token", async () => {
+    apiPost.mockResolvedValue({
+      connection: { ...SAMPLE_INFO, auth_token: "fresh-tok-123" },
+    });
+    render(<ExternalConnectionSection workspaceId="ws-test" />);
+
+    fireEvent.click(screen.getByRole("button", { name: /rotate credentials/i }));
+    await waitFor(() =>
+      expect(screen.getByText(/Rotate workspace credentials\?/i)).toBeTruthy(),
+    );
+    // Click the dialog's Rotate button (NOT the section's — the section's
+    // "Rotate credentials" stays mounted; the dialog's "Rotate" is the
+    // commit button. getAllByRole returns both; pick the one inside the
+    // dialog by name "Rotate" exact-match).
+    const rotateBtns = screen.getAllByRole("button", { name: /^rotate$/i });
+    expect(rotateBtns.length).toBeGreaterThanOrEqual(1);
+    fireEvent.click(rotateBtns[rotateBtns.length - 1]);
+
+    await waitFor(() =>
+      expect(apiPost).toHaveBeenCalledWith(
+        "/workspaces/ws-test/external/rotate",
+        {},
+      ),
+    );
+  });
+
+  it("Surfaces API errors as a visible chip, not silent loss", async () => {
+    apiGet.mockRejectedValue(new Error("forbidden"));
+    render(<ExternalConnectionSection workspaceId="ws-test" />);
+
+    fireEvent.click(screen.getByRole("button", { name: /show connection info/i }));
+
+    await waitFor(() => {
+      const matches = screen.queryAllByText((_, el) =>
+        (el?.textContent || "").toLowerCase().includes("forbidden"),
+      );
+      expect(matches.length).toBeGreaterThan(0);
+    });
+  });
+});
@@ -0,0 +1,220 @@
+// @vitest-environment jsdom
+//
+// Pins the Edit affordance added to MemoryTab. Until this PR the Memory tab
+// was Add+Delete only; an entry that needed correction had to be deleted and
+// re-added — losing the version-counter and any in-flight optimistic-locking
+// invariants other writers depend on.
+//
+// Each test pins one branch of the new flow. If any fails, the bug is back.
+
+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 apiPost = vi.fn();
+const apiDel = vi.fn();
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: (path: string) => apiGet(path),
+    post: (path: string, body: unknown) => apiPost(path, body),
+    del: (path: string) => apiDel(path),
+    patch: vi.fn(),
+    put: vi.fn(),
+  },
+}));
+
+import { MemoryTab } from "../MemoryTab";
+
+const sampleEntries = [
+  {
+    key: "team_brief",
+    value: { goal: "ship v2" },
+    version: 3,
+    expires_at: null,
+    updated_at: "2026-05-04T10:00:00Z",
+  },
+  {
+    key: "plain_note",
+    value: "raw text note",
+    version: 1,
+    expires_at: "2099-01-01T00:00:00Z",
+    updated_at: "2026-05-04T10:01:00Z",
+  },
+];
+
+beforeEach(() => {
+  apiGet.mockReset();
+  apiPost.mockReset();
+  apiDel.mockReset();
+  apiGet.mockImplementation((path: string) => {
+    if (path === "/workspaces/ws-test/memory") {
+      return Promise.resolve(sampleEntries);
+    }
+    return Promise.reject(new Error(`unmocked api.get: ${path}`));
+  });
+});
+
+async function renderAndExpand(key: string) {
+  render(<MemoryTab workspaceId="ws-test" />);
+  await waitFor(() => expect(apiGet).toHaveBeenCalled());
+  // Reveal the Advanced section that hosts the entry list.
+  const showAdvanced = await screen.findByRole("button", { name: "Show" });
+  fireEvent.click(showAdvanced);
+  // Expand the row.
+  const row = await screen.findByRole("button", { name: new RegExp(key) });
+  fireEvent.click(row);
+}
+
+describe("MemoryTab Edit affordance", () => {
+  it("Edit button appears once a row is expanded", async () => {
+    await renderAndExpand("team_brief");
+    expect(screen.getAllByRole("button", { name: "Edit" }).length).toBeGreaterThan(0);
+  });
+
+  it("clicking Edit on a JSON-valued entry pre-fills the textarea with pretty JSON", async () => {
+    await renderAndExpand("team_brief");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    const textarea = (await screen.findByLabelText(
+      "Edit value for team_brief",
+    )) as HTMLTextAreaElement;
+    expect(textarea.value).toBe('{\n  "goal": "ship v2"\n}');
+  });
+
+  it("clicking Edit on a string-valued entry pre-fills raw (no surrounding quotes)", async () => {
+    await renderAndExpand("plain_note");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    const textarea = (await screen.findByLabelText(
+      "Edit value for plain_note",
+    )) as HTMLTextAreaElement;
+    expect(textarea.value).toBe("raw text note");
+  });
+
+  it("Save POSTs with if_match_version + parsed value, then reloads", async () => {
+    apiPost.mockResolvedValue({ status: "ok", key: "team_brief", version: 4 });
+    await renderAndExpand("team_brief");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    const textarea = await screen.findByLabelText("Edit value for team_brief");
+    fireEvent.change(textarea, { target: { value: '{"goal":"ship v3"}' } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() => expect(apiPost).toHaveBeenCalledTimes(1));
+    expect(apiPost).toHaveBeenCalledWith("/workspaces/ws-test/memory", {
+      key: "team_brief",
+      value: { goal: "ship v3" },
+      if_match_version: 3,
+    });
+    // Reload after save → second GET.
+    await waitFor(() => expect(apiGet).toHaveBeenCalledTimes(2));
+  });
+
+  it("Save with non-JSON text falls back to plain string", async () => {
+    apiPost.mockResolvedValue({ status: "ok" });
+    await renderAndExpand("team_brief");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    const textarea = await screen.findByLabelText("Edit value for team_brief");
+    fireEvent.change(textarea, { target: { value: "free-form note" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() => expect(apiPost).toHaveBeenCalledTimes(1));
+    expect(apiPost.mock.calls[0][1].value).toBe("free-form note");
+  });
+
+  it("TTL field is forwarded as ttl_seconds when set", async () => {
+    apiPost.mockResolvedValue({ status: "ok" });
+    await renderAndExpand("team_brief");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    const ttlInput = await screen.findByLabelText("Edit TTL for team_brief");
+    fireEvent.change(ttlInput, { target: { value: "3600" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() => expect(apiPost).toHaveBeenCalledTimes(1));
+    expect(apiPost.mock.calls[0][1].ttl_seconds).toBe(3600);
+  });
+
+  it("blank/zero/non-numeric TTL is omitted from the payload", async () => {
+    apiPost.mockResolvedValue({ status: "ok" });
+    await renderAndExpand("team_brief");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    const ttlInput = await screen.findByLabelText("Edit TTL for team_brief");
+    // Junk + zero both must drop out — payload must not contain ttl_seconds.
+    fireEvent.change(ttlInput, { target: { value: "abc" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+    await waitFor(() => expect(apiPost).toHaveBeenCalledTimes(1));
+    expect(apiPost.mock.calls[0][1]).not.toHaveProperty("ttl_seconds");
+  });
+
+  it("Cancel discards edits and restores the rendered value", async () => {
+    await renderAndExpand("team_brief");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    const textarea = await screen.findByLabelText("Edit value for team_brief");
+    fireEvent.change(textarea, { target: { value: '{"goal":"discarded"}' } });
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+
+    expect(apiPost).not.toHaveBeenCalled();
+    // Editor is gone; the JSON pre-block is back.
+    expect(screen.queryByLabelText("Edit value for team_brief")).toBeNull();
+    expect(screen.getAllByText(/"goal": "ship v2"/i).length).toBeGreaterThan(0);
+  });
+
+  it("409 response surfaces a retry hint and reloads", async () => {
+    apiPost.mockRejectedValueOnce(
+      new Error("HTTP 409: if_match_version mismatch"),
+    );
+    await renderAndExpand("team_brief");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    const textarea = await screen.findByLabelText("Edit value for team_brief");
+    fireEvent.change(textarea, { target: { value: '{"goal":"ship v3"}' } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() => expect(apiPost).toHaveBeenCalledTimes(1));
+    const alert = await screen.findByRole("alert");
+    expect(alert.textContent).toMatch(/changed since you opened it/i);
+    // Initial mount load + post-conflict reload.
+    await waitFor(() => expect(apiGet).toHaveBeenCalledTimes(2));
+  });
+
+  it("non-409 error surfaces the message and does not reload", async () => {
+    apiPost.mockRejectedValueOnce(new Error("boom"));
+    await renderAndExpand("team_brief");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    const alert = await screen.findByRole("alert");
+    expect(alert.textContent).toBe("boom");
+    // Only the initial mount load — no retry reload.
+    expect(apiGet).toHaveBeenCalledTimes(1);
+  });
+
+  it("entry with no version omits if_match_version (back-compat with older shape)", async () => {
+    // Pre-version-counter shape: drop the `version` field from the row.
+    apiGet.mockReset();
+    apiGet.mockImplementation((path: string) => {
+      if (path === "/workspaces/ws-test/memory") {
+        return Promise.resolve([
+          {
+            key: "old_entry",
+            value: "legacy",
+            expires_at: null,
+            updated_at: "2026-05-04T10:00:00Z",
+          },
+        ]);
+      }
+      return Promise.reject(new Error(`unmocked: ${path}`));
+    });
+    apiPost.mockResolvedValue({ status: "ok" });
+
+    await renderAndExpand("old_entry");
+    fireEvent.click(screen.getAllByRole("button", { name: "Edit" })[0]);
+    const textarea = await screen.findByLabelText("Edit value for old_entry");
+    fireEvent.change(textarea, { target: { value: "updated" } });
+    fireEvent.click(screen.getByRole("button", { name: "Save" }));
+
+    await waitFor(() => expect(apiPost).toHaveBeenCalledTimes(1));
+    const payload = apiPost.mock.calls[0][1];
+    expect(payload).not.toHaveProperty("if_match_version");
+    expect(payload.value).toBe("updated");
+  });
+});
@@ -0,0 +1,107 @@
+// @vitest-environment jsdom
+//
+// Pins the "Terminal not available" early-return added 2026-05-05.
+//
+// Pre-fix: TerminalTab tried to open /ws/terminal/<id> for every
+// workspace including external runtimes (which have no shell endpoint).
+// The server returned 404, status flipped to "error", user saw
+// "Connection failed" with a Reconnect button — reading as a bug
+// when really the runtime intentionally has no TTY. Now: when
+// data.runtime is in RUNTIMES_WITHOUT_TERMINAL, render a banner +
+// big icon instead of mounting xterm/WS.
+//
+// Pinned branches:
+//   1. external runtime → "Terminal not available" banner renders,
+//      runtime name surfaces in the body so the user knows WHY.
+//   2. external runtime → xterm + WebSocket are NOT initialised.
+//      Verified by checking the global WebSocket constructor isn't
+//      called.
+//   3. claude-code (or any other runtime) → no banner, normal mount
+//      proceeds. Pre-fix regression cover.
+//   4. data prop omitted (back-compat with any caller that doesn't
+//      thread it through) → no early-return, falls through to normal
+//      mount. Tested via the absence of the banner.
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import React from "react";
+
+afterEach(cleanup);
+
+// xterm + addon-fit are dynamically imported by TerminalTab. Stub them
+// so the tests don't pull a 200KB+ dependency just to verify the
+// not-available banner. The stubs only matter for the non-banner
+// branches; the banner returns BEFORE the dynamic import.
+vi.mock("xterm", () => ({
+  Terminal: vi.fn().mockImplementation(() => ({
+    loadAddon: vi.fn(),
+    open: vi.fn(),
+    onData: vi.fn(),
+    write: vi.fn(),
+    dispose: vi.fn(),
+    onResize: vi.fn(),
+    cols: 80,
+    rows: 24,
+  })),
+}));
+vi.mock("@xterm/addon-fit", () => ({
+  FitAddon: vi.fn().mockImplementation(() => ({
+    fit: vi.fn(),
+  })),
+}));
+
+// Track WebSocket constructor calls — this is the load-bearing
+// assertion for "external doesn't even try to connect".
+let wsConstructed = 0;
+beforeEach(() => {
+  wsConstructed = 0;
+  (globalThis as unknown as { WebSocket: unknown }).WebSocket = vi
+    .fn()
+    .mockImplementation(() => {
+      wsConstructed++;
+      return {
+        addEventListener: vi.fn(),
+        removeEventListener: vi.fn(),
+        send: vi.fn(),
+        close: vi.fn(),
+        readyState: 0,
+      };
+    });
+});
+
+import { TerminalTab } from "../TerminalTab";
+
+const externalData = { runtime: "external", status: "online" } as unknown as Parameters<
+  typeof TerminalTab
+>[0]["data"];
+
+const claudeData = { runtime: "claude-code", status: "online" } as unknown as Parameters<
+  typeof TerminalTab
+>[0]["data"];
+
+describe("TerminalTab not-available early-return for runtimes without TTY", () => {
+  it("external runtime renders the not-available banner with runtime name", () => {
+    render(<TerminalTab workspaceId="ws-ext" data={externalData} />);
+    expect(screen.getByText(/Terminal not available/i)).not.toBeNull();
+    // Runtime name surfaces so user knows WHY there's no terminal.
+    expect(screen.getByText(/external/)).not.toBeNull();
+  });
+
+  it("external runtime does NOT open a WebSocket", async () => {
+    render(<TerminalTab workspaceId="ws-ext" data={externalData} />);
+    // Wait a tick for any deferred init (there shouldn't be any, but
+    // tolerate a microtask boundary).
+    await new Promise((r) => setTimeout(r, 0));
+    expect(wsConstructed).toBe(0);
+  });
+
+  it("claude-code runtime does NOT render the banner (normal mount)", () => {
+    render(<TerminalTab workspaceId="ws-claude" data={claudeData} />);
+    expect(screen.queryByText(/Terminal not available/i)).toBeNull();
+  });
+
+  it("data prop omitted falls through to normal mount (back-compat)", () => {
+    render(<TerminalTab workspaceId="ws-no-data" />);
+    expect(screen.queryByText(/Terminal not available/i)).toBeNull();
+  });
+});
@@ -1,6 +1,6 @@
 "use client";

-import { useState, useEffect, useMemo, useRef } from "react";
+import { useState, useEffect, useLayoutEffect, useMemo, useRef, useCallback } from "react";
 import ReactMarkdown from "react-markdown";
 import remarkGfm from "remark-gfm";
 import { api } from "@/lib/api";
@@ -184,13 +184,23 @@ function unwrapErrorText(raw: string | null): string {
 export function AgentCommsPanel({ workspaceId }: { workspaceId: string }) {
  const [messages, setMessages] = useState<CommMessage[]>([]);
  const [loading, setLoading] = useState(true);
+  const [loadError, setLoadError] = useState<string | null>(null);
  // Dedup by timestamp+type+peer to handle API load + WebSocket race
  const seenKeys = useRef(new Set<string>());
  const bottomRef = useRef<HTMLDivElement>(null);
+  // Mirrors the my-chat scroll behaviour from ChatTab (PR #2903) —
+  // smooth-scroll on a long history gets interrupted by concurrent
+  // renders and lands the panel mid-conversation. Switch the first
+  // arrival to instant; subsequent appends animate.
+  const hasInitialScrollRef = useRef(false);

-  // Load history
-  useEffect(() => {
+  // Load history. Extracted so the error-state retry button can
+  // re-invoke without remount. ChatTab uses the same shape
+  // (loadInitial → loadError state → retry button).
+  const loadInitial = useCallback(() => {
    setLoading(true);
+    setLoadError(null);
+    seenKeys.current.clear();
    api.get<ActivityEntry[]>(`/workspaces/${workspaceId}/activity?source=agent&limit=50`)
      .then((entries) => {
        const filtered = (entries ?? [])
@@ -234,10 +244,15 @@ export function AgentCommsPanel({ workspaceId }: { workspaceId: string }) {
        // the .then body) — the panel just sat on the empty state
        // with zero signal.
        console.warn("AgentCommsPanel: load activity failed", err);
+        setLoadError(err instanceof Error ? err.message : String(err));
        setLoading(false);
      });
  }, [workspaceId]);

+  useEffect(() => {
+    loadInitial();
+  }, [loadInitial]);
+
  // Live updates routed through the global ReconnectingSocket. The
  // previous pattern of `new WebSocket(WS_URL)` per panel had no
  // onclose / no reconnect, so any drop (idle timeout, browser
@@ -358,7 +373,18 @@ export function AgentCommsPanel({ workspaceId }: { workspaceId: string }) {
    } catch { /* ignore */ }
  });

-  useEffect(() => {
+  // useLayoutEffect (not useEffect) so the scroll runs BEFORE paint —
+  // otherwise the user sees the panel jump for one frame on every
+  // append. Mirrors ChatTab's MyChatPanel scroll block.
+  useLayoutEffect(() => {
+    if (!hasInitialScrollRef.current && messages.length > 0) {
+      // Instant on first arrival — smooth-scroll on a long history
+      // gets interrupted by concurrent renders and lands the panel
+      // mid-conversation (the chat-opens-in-middle bug class).
+      hasInitialScrollRef.current = true;
+      bottomRef.current?.scrollIntoView({ behavior: "instant" as ScrollBehavior });
+      return;
+    }
    bottomRef.current?.scrollIntoView({ behavior: "smooth" });
  }, [messages]);

@@ -366,6 +392,27 @@ export function AgentCommsPanel({ workspaceId }: { workspaceId: string }) {
    return <div className="text-xs text-ink-soft text-center py-8">Loading agent communications...</div>;
  }

+  if (loadError !== null && messages.length === 0) {
+    // Mirrors ChatTab my-chat error UI — surfaces the load failure
+    // with a retry button instead of silently rendering empty state.
+    return (
+      <div
+        role="alert"
+        className="mx-2 mt-2 rounded-lg border border-red-800/50 bg-red-950/30 px-3 py-2.5"
+      >
+        <p className="text-[11px] text-bad mb-1.5">
+          Failed to load agent communications: {loadError}
+        </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"
+        >
+          Retry
+        </button>
+      </div>
+    );
+  }
+
  if (messages.length === 0) {
    return (
      <div className="text-xs text-ink-soft text-center py-8">
@@ -472,6 +519,7 @@ function GroupedCommsView({
            <NormalMessage key={msg.id} msg={msg} />
          ),
        )}
+        <WaitingBubbles visible={visible} />
        <div ref={bottomRef} />
      </div>
    </div>
@@ -560,6 +608,83 @@ function PeerTabButton({
  );
 }

+/** WaitingBubbles renders one "typing" bubble per peer that has an
+ *  in-flight outbound delegation — i.e., the most recent outbound
+ *  message to that peer is still pending or queued and no later inbound
+ *  reply has arrived. Mirrors the bouncing-dots indicator in ChatTab so
+ *  the operator sees the same visual cue regardless of whether they're
+ *  watching their own chat or a peer thread.
+ *
+ *  Why "per peer" not "one global": when multiple delegations are in
+ *  flight to different peers (common during fan-out), one shared
+ *  spinner under-reports — the user can't tell whether ALL peers are
+ *  still working or only the visible ones. Per-peer matches Slack-style
+ *  typing indicators and keeps the signal honest.
+ *
+ *  Why we look at the LAST per-peer message: once a peer replies (an
+ *  "in" bubble lands), the corresponding "out" bubble is no longer the
+ *  tail — even if status hasn't been mutated to "completed", the inbound
+ *  reply means the wait is over. Looking at the tail collapses both
+ *  cases into one rule.
+ */
+function WaitingBubbles({ visible }: { visible: CommMessage[] }) {
+  // Group by peer, keep only the chronologically-last message per peer,
+  // emit a bubble when that tail is an outbound pending/queued.
+  const tailByPeer = new Map<string, CommMessage>();
+  for (const m of visible) {
+    const prev = tailByPeer.get(m.peerId);
+    if (!prev || m.timestamp > prev.timestamp) tailByPeer.set(m.peerId, m);
+  }
+  const waitingPeers = Array.from(tailByPeer.values()).filter(
+    (m) => m.flow === "out" && (m.status === "pending" || m.status === "queued"),
+  );
+  if (waitingPeers.length === 0) return null;
+  return (
+    <>
+      {waitingPeers.map((m) => (
+        <div
+          key={`waiting-${m.peerId}`}
+          className="flex justify-end"
+          // Outbound thread → right-justified to match the "out" bubble
+          // alignment, so the dots feel like they belong to the message
+          // they're replying to.
+        >
+          <div
+            className="max-w-[85%] rounded-lg px-3 py-2 text-xs bg-cyan-900/30 border border-cyan-700/20"
+            // role+aria-label so screen readers announce the wait;
+            // matches the announcing pattern used by Toaster.
+            role="status"
+            aria-label={`Waiting for reply from ${m.peerName}`}
+          >
+            <div className="text-[9px] text-ink-soft mb-1">→ To {m.peerName}</div>
+            <span className="flex items-center gap-2 text-ink-mid">
+              <span className="flex gap-0.5" aria-hidden="true">
+                <span
+                  className="w-1.5 h-1.5 bg-cyan-300/70 rounded-full motion-safe:animate-bounce"
+                  style={{ animationDelay: "0ms" }}
+                />
+                <span
+                  className="w-1.5 h-1.5 bg-cyan-300/70 rounded-full motion-safe:animate-bounce"
+                  style={{ animationDelay: "150ms" }}
+                />
+                <span
+                  className="w-1.5 h-1.5 bg-cyan-300/70 rounded-full motion-safe:animate-bounce"
+                  style={{ animationDelay: "300ms" }}
+                />
+              </span>
+              <span className="text-[10px]">
+                {m.status === "queued"
+                  ? `${m.peerName} is busy — reply will arrive when they're free`
+                  : `Waiting for ${m.peerName}…`}
+              </span>
+            </span>
+          </div>
+        </div>
+      ))}
+    </>
+  );
+}
+
 function NormalMessage({ msg }: { msg: CommMessage }) {
  return (
    <div className={`flex ${msg.flow === "out" ? "justify-end" : "justify-start"}`}>
@@ -574,12 +699,22 @@ function NormalMessage({ msg }: { msg: CommMessage }) {
          {msg.flow === "out" ? `→ To ${msg.peerName}` : `← From ${msg.peerName}`}
        </div>
        {msg.text ? (
-          <MarkdownBody className="text-ink-mid">{msg.text}</MarkdownBody>
+          // Outgoing bubble (cyan-900) is dark in both themes → prose-invert default.
+          // Incoming bubble (surface-card) themes light → only invert in dark.
+          <MarkdownBody
+            className="text-ink-mid"
+            invert={msg.flow === "out" ? "always" : "dark-only"}
+          >
+            {msg.text}
+          </MarkdownBody>
        ) : (
          <div className="text-ink-mid">(no message text)</div>
        )}
        {msg.responseText && (
-          <MarkdownBody className="mt-1.5 pt-1.5 border-t border-line/30 text-ink-mid">
+          <MarkdownBody
+            className="mt-1.5 pt-1.5 border-t border-line/30 text-ink-mid"
+            invert={msg.flow === "out" ? "always" : "dark-only"}
+          >
            {msg.responseText}
          </MarkdownBody>
        )}
@@ -706,17 +841,29 @@ function ErrorMessage({ msg }: { msg: CommMessage }) {
 *  prose tweaks that keep paragraphs tight inside a small bubble.
 *  Code blocks get an `overflow-x-auto` so a long line of code doesn't
 *  blow out the bubble's max-width — agent-to-agent replies routinely
- *  ship code samples and JSON. */
+ *  ship code samples and JSON.
+ *
+ *  `invert` controls the prose color flip:
+ *  - "always": container bg is dark in BOTH themes (cyan-900, red-950),
+ *    so prose always wants light body text.
+ *  - "dark-only": container bg uses a theming token that goes light in
+ *    light mode (e.g. bg-surface-card). Prose only inverts in dark
+ *    mode; light mode keeps default dark prose colors against the
+ *    light bg. Without this, light mode rendered light text on light
+ *    bg = invisible markdown. */
 function MarkdownBody({
  children,
  className,
+  invert = "always",
 }: {
  children: string;
  className?: string;
+  invert?: "always" | "dark-only";
 }) {
+  const proseInvert = invert === "always" ? "prose-invert" : "dark:prose-invert";
  return (
    <div
-      className={`prose prose-sm prose-invert max-w-none [&>p]:mb-1 [&>p:last-child]:mb-0 [&_pre]:overflow-x-auto [&_table]:block [&_table]:overflow-x-auto ${className ?? ""}`}
+      className={`prose prose-sm ${proseInvert} max-w-none [&>p]:mb-1 [&>p:last-child]:mb-0 [&_pre]:overflow-x-auto [&_table]:block [&_table]:overflow-x-auto ${className ?? ""}`}
    >
      <ReactMarkdown remarkPlugins={[remarkGfm]}>{children}</ReactMarkdown>
    </div>
@@ -0,0 +1,115 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, screen, fireEvent, waitFor } from "@testing-library/react";
+
+// API mock — tests can override per case via apiGetMock.mockImplementationOnce.
+const apiGetMock = vi.fn<(url: string) => Promise<unknown>>();
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: (url: string) => apiGetMock(url),
+  },
+}));
+
+// useSocketEvent — no-op for these render tests; live updates aren't
+// what we're verifying here.
+vi.mock("@/hooks/useSocketEvent", () => ({
+  useSocketEvent: () => {},
+}));
+
+// Canvas store — peer name resolution.
+vi.mock("@/store/canvas", () => ({
+  useCanvasStore: {
+    getState: () => ({
+      nodes: [
+        { id: "ws-self", data: { name: "Self" } },
+        { id: "ws-peer", data: { name: "Peer Agent" } },
+      ],
+    }),
+  },
+}));
+
+// Toaster shim — AgentCommsPanel imports showToast.
+vi.mock("../../Toaster", () => ({
+  showToast: vi.fn(),
+}));
+
+import { AgentCommsPanel } from "../AgentCommsPanel";
+
+// jsdom doesn't implement scrollIntoView. Tests that observe the call
+// install a spy here; tests that don't care still need a no-op stub
+// so the component doesn't throw.
+const scrollSpy = vi.fn<(opts?: ScrollIntoViewOptions | boolean) => void>();
+beforeEach(() => {
+  apiGetMock.mockReset();
+  scrollSpy.mockReset();
+  Element.prototype.scrollIntoView = scrollSpy as unknown as Element["scrollIntoView"];
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("AgentCommsPanel — initial-state parity with ChatTab my-chat", () => {
+  it("shows loading text while history fetch is in flight", () => {
+    apiGetMock.mockReturnValueOnce(new Promise(() => { /* never resolves */ }));
+    render(<AgentCommsPanel workspaceId="ws-self" />);
+    expect(screen.getByText("Loading agent communications...")).toBeDefined();
+  });
+
+  it("renders error UI with a Retry button when the history fetch rejects", async () => {
+    apiGetMock.mockRejectedValueOnce(new Error("network down"));
+    render(<AgentCommsPanel workspaceId="ws-self" />);
+
+    // Wait for the error state to render — loading→error transition is async.
+    const alert = await waitFor(() => screen.getByRole("alert"));
+    expect(alert.textContent).toMatch(/Failed to load agent communications/);
+    expect(alert.textContent).toMatch(/network down/);
+
+    // Retry button must be present and trigger a refetch.
+    const retry = screen.getByRole("button", { name: "Retry" });
+    apiGetMock.mockResolvedValueOnce([]); // success on retry
+    fireEvent.click(retry);
+
+    // Two calls total: initial load + retry. Pin via mock call count.
+    await waitFor(() => expect(apiGetMock.mock.calls.length).toBe(2));
+  });
+
+  it("falls back to empty-state copy when load succeeds with zero rows", async () => {
+    apiGetMock.mockResolvedValueOnce([]);
+    render(<AgentCommsPanel workspaceId="ws-self" />);
+    await waitFor(() =>
+      expect(screen.getByText("No agent-to-agent communications yet.")).toBeDefined(),
+    );
+  });
+
+  it("scrollIntoView is called with behavior=instant on the first message arrival", async () => {
+    apiGetMock.mockResolvedValueOnce([
+      {
+        id: "act-1",
+        activity_type: "a2a_send",
+        source_id: "ws-self",
+        target_id: "ws-peer",
+        method: "message/send",
+        summary: "Delegating",
+        request_body: { message: { parts: [{ text: "hi" }] } },
+        response_body: null,
+        status: "ok",
+        created_at: "2026-04-25T18:00:00Z",
+      },
+    ]);
+    render(<AgentCommsPanel workspaceId="ws-self" />);
+
+    // useLayoutEffect is what makes the first call instant — wait for
+    // the panel to render at least one message.
+    await waitFor(() => expect(scrollSpy.mock.calls.length).toBeGreaterThan(0));
+
+    // The pinned contract: SOME call uses behavior: "instant" — the
+    // first-arrival case. Subsequent appends use "smooth", but those
+    // can't fire here (no live update yet).
+    const sawInstant = scrollSpy.mock.calls.some((args) => {
+      const opts = args[0];
+      return typeof opts === "object" && opts !== null && "behavior" in opts && opts.behavior === "instant";
+    });
+    expect(sawInstant).toBe(true);
+  });
+});
@@ -22,7 +22,6 @@ export interface ConfigData {
  // task_budget maps to output_config.task_budget.total (requires beta header task-budgets-2026-03-13)
  task_budget?: number;
  prompt_files: string[];
-  shared_context: string[];
  skills: string[];
  tools: string[];
  a2a: { port: number; streaming: boolean; push_notifications: boolean };
@@ -40,7 +39,6 @@ export const DEFAULT_CONFIG: ConfigData = {
  effort: "",
  task_budget: 0,
  prompt_files: [],
-  shared_context: [],
  skills: [],
  tools: [],
  a2a: { port: 8000, streaming: true, push_notifications: true },
@@ -120,7 +120,6 @@ export function toYaml(config: ConfigData): string {
  if (config.effort) { lines.push(""); simple("effort", config.effort); }
  if (config.task_budget && config.task_budget > 0) { simple("task_budget", config.task_budget); }
  if (config.prompt_files?.length) { lines.push(""); list("prompt_files", config.prompt_files); }
-  if (config.shared_context?.length) { lines.push(""); list("shared_context", config.shared_context); }
  lines.push(""); list("skills", config.skills);
  if (config.tools?.length) { list("tools", config.tools); }
  lines.push(""); obj("a2a", config.a2a as unknown as Record<string, unknown>);
@@ -2,7 +2,7 @@
 * @vitest-environment jsdom
 */
 import { describe, it, expect, vi, afterEach } from "vitest";
-import { fetchSession, redirectToLogin } from "../auth";
+import { fetchSession, redirectToLogin, signOut } from "../auth";

 afterEach(() => {
  vi.unstubAllGlobals();
@@ -110,3 +110,157 @@ describe("redirectToLogin", () => {
    expect((window.location as unknown as { href: string }).href).toBe(signupHref);
  });
 });
+
+describe("signOut", () => {
+  // Helper — most tests need the same window.location stub.
+  function stubLocation(): void {
+    Object.defineProperty(window, "location", {
+      writable: true,
+      value: {
+        href: "https://acme.moleculesai.app/orgs",
+        pathname: "/orgs",
+        hostname: "acme.moleculesai.app",
+        protocol: "https:",
+      },
+    });
+  }
+
+  it("POSTs to /cp/auth/signout with credentials:include", async () => {
+    stubLocation();
+    const fetchMock = vi.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      json: async () => ({ ok: true, logout_url: "" }),
+    });
+    vi.stubGlobal("fetch", fetchMock);
+
+    await signOut();
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(fetchMock).toHaveBeenCalledWith(
+      expect.stringContaining("/cp/auth/signout"),
+      expect.objectContaining({ method: "POST", credentials: "include" }),
+    );
+  });
+
+  it("navigates to provider logout_url when the response includes one", async () => {
+    // The hosted-logout path is what actually breaks the SSO re-auth
+    // loop reported on PR #2913. Without this, AuthKit's browser
+    // cookie keeps the user signed in via SSO and any subsequent
+    // /cp/auth/login silently re-auths.
+    stubLocation();
+    const hostedLogout =
+      "https://api.workos.com/user_management/sessions/logout?session_id=cookie&return_to=https%3A%2F%2Fapp.moleculesai.app%2Forgs";
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({ ok: true, logout_url: hostedLogout }),
+      }),
+    );
+
+    await signOut();
+
+    const after = (window.location as unknown as { href: string }).href;
+    expect(after).toBe(hostedLogout);
+  });
+
+  it("falls back to /cp/auth/login when logout_url is empty (DisabledProvider / dev)", async () => {
+    // DisabledProvider returns "" — the local /cp/auth/login redirect
+    // works in dev/test where there's no SSO session to escape.
+    stubLocation();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({ ok: true, logout_url: "" }),
+      }),
+    );
+
+    await signOut();
+
+    const after = (window.location as unknown as { href: string }).href;
+    // Tenant subdomain (acme.moleculesai.app) → auth origin is app.moleculesai.app.
+    expect(after).toBe("https://app.moleculesai.app/cp/auth/login");
+  });
+
+  it("redirects even when the POST fails so the user isn't stuck on an authed page", async () => {
+    // Critical UX invariant: clicking 'Sign out' MUST navigate away from
+    // the authenticated app, even if the network is down or the cookie
+    // is already invalid. Anything else looks like the button is
+    // broken — the precise complaint that triggered this fix.
+    stubLocation();
+    vi.stubGlobal("fetch", vi.fn().mockRejectedValue(new Error("network down")));
+
+    await signOut();
+
+    const after = (window.location as unknown as { href: string }).href;
+    expect(after).toBe("https://app.moleculesai.app/cp/auth/login");
+  });
+
+  it("redirects on 401 (session already invalid) just like 200", async () => {
+    // A user with an already-invalid cookie should still see the
+    // logout flow complete — no error, no stuck-on-app dead end.
+    // Note: 401 means res.ok=false → we don't read .json() at all,
+    // so a missing body is fine.
+    stubLocation();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: false,
+        status: 401,
+        json: async () => ({}),
+      }),
+    );
+
+    await signOut();
+
+    const after = (window.location as unknown as { href: string }).href;
+    expect(after).toBe("https://app.moleculesai.app/cp/auth/login");
+  });
+
+  it("falls back to /cp/auth/login when the response body is malformed", async () => {
+    // Defensive parsing: a body that isn't valid JSON, or doesn't
+    // have logout_url, or has logout_url as the wrong type — none of
+    // these should strand the user on the authed page. Fallback path
+    // takes over.
+    stubLocation();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => {
+          throw new Error("not json");
+        },
+      }),
+    );
+
+    await signOut();
+
+    const after = (window.location as unknown as { href: string }).href;
+    expect(after).toBe("https://app.moleculesai.app/cp/auth/login");
+  });
+
+  it("falls back to /cp/auth/login when logout_url is the wrong type", async () => {
+    // Even valid JSON should be type-checked: a non-string logout_url
+    // (e.g. server-side bug, version drift) must not crash or open-
+    // redirect the user.
+    stubLocation();
+    vi.stubGlobal(
+      "fetch",
+      vi.fn().mockResolvedValue({
+        ok: true,
+        status: 200,
+        json: async () => ({ ok: true, logout_url: 42 }),
+      }),
+    );
+
+    await signOut();
+
+    const after = (window.location as unknown as { href: string }).href;
+    expect(after).toBe("https://app.moleculesai.app/cp/auth/login");
+  });
+});
@@ -67,3 +67,80 @@ export function redirectToLogin(screenHint: "sign-up" | "sign-in" = "sign-in"):
  const dest = `${authOrigin}${AUTH_BASE}/${path}?return_to=${encodeURIComponent(returnTo)}`;
  window.location.href = dest;
 }
+
+/**
+ * signOut posts to /cp/auth/signout to clear the WorkOS session cookie
+ * + revoke at the provider, then navigates the browser to the
+ * provider-supplied hosted logout URL (so the provider's BROWSER-side
+ * SSO cookie is cleared too — without this, AuthKit silently re-auths
+ * via SSO on the next /cp/auth/login and the user is "still signed
+ * in" after pressing Sign out).
+ *
+ * Two-layer flow:
+ *  1. POST /cp/auth/signout → CP clears OUR session cookie + revokes
+ *     session_id at the provider API. Response includes
+ *     `logout_url` — the AuthKit hosted URL the BROWSER must navigate
+ *     to so the provider's own browser cookie is cleared.
+ *  2. window.location.href = <logout_url> → AuthKit clears its
+ *     session, then redirects the browser to the configured
+ *     return_to (defaults to APP_URL/orgs).
+ *
+ * Best-effort by design: a 5xx, network failure, missing logout_url
+ * (DisabledProvider, dev), or stale cookie still results in the
+ * browser navigating away — leaving the user on a logged-in-looking
+ * page after they clicked "Sign out" is the worst possible UX. The
+ * fallback path navigates to /cp/auth/login on the auth origin, which
+ * works correctly in environments without a hosted logout flow (dev,
+ * tests, DisabledProvider).
+ *
+ * Throws nothing — callers can disable the button optimistically or
+ * await this and trust it returns. On a redirect-blocked test
+ * environment (jsdom under vitest) we still exit cleanly so unit tests
+ * can spy on the fetch call.
+ */
+export async function signOut(): Promise<void> {
+  let logoutURL: string | undefined;
+  // Fire-and-tolerate the POST. credentials:include is mandatory cross-
+  // origin so the SaaS canvas (acme.moleculesai.app) can hit
+  // app.moleculesai.app/cp/auth/signout with the session cookie.
+  try {
+    const res = await fetch(`${getAuthOrigin()}${AUTH_BASE}/signout`, {
+      method: "POST",
+      credentials: "include",
+    });
+    if (res.ok) {
+      // Body shape: {"ok": true, "logout_url": "..."}. logout_url is
+      // empty for DisabledProvider (dev/local) — we fall back to
+      // /cp/auth/login below. Defensive parsing: a malformed body
+      // shouldn't strand the user on the authed page.
+      const body: unknown = await res.json().catch(() => null);
+      if (
+        body &&
+        typeof body === "object" &&
+        "logout_url" in body &&
+        typeof (body as { logout_url: unknown }).logout_url === "string" &&
+        (body as { logout_url: string }).logout_url
+      ) {
+        logoutURL = (body as { logout_url: string }).logout_url;
+      }
+    }
+  } catch {
+    // Ignore — we still redirect below.
+  }
+  if (typeof window === "undefined") return;
+  if (logoutURL) {
+    // Hosted logout: AuthKit clears its SSO cookie + redirects to
+    // return_to (configured server-side). This is the path that
+    // actually breaks the SSO re-auth loop.
+    window.location.href = logoutURL;
+    return;
+  }
+  // Fallback: no hosted logout (dev, DisabledProvider, network
+  // failure). Land on the login screen rather than the current URL:
+  // returning to a tenant URL after signout would just re-redirect
+  // through /cp/auth/login due to AuthGate. Send the user straight
+  // there with no return_to so they don't loop back into the org they
+  // just left.
+  const authOrigin = getAuthOrigin();
+  window.location.href = `${authOrigin}${AUTH_BASE}/login`;
+}
@@ -5,6 +5,13 @@ export const STATUS_CONFIG: Record<string, { dot: string; glow: string; label: s
  degraded: { dot: "bg-amber-400", glow: "shadow-amber-400/50", label: "Degraded", bar: "from-amber-500/20 to-transparent" },
  failed: { dot: "bg-red-400", glow: "shadow-red-400/50", label: "Failed", bar: "from-red-500/20 to-transparent" },
  provisioning: { dot: "bg-sky-400 motion-safe:animate-pulse", glow: "shadow-sky-400/50", label: "Starting", bar: "from-sky-500/20 to-transparent" },
+  // not_configured: derived state from agent_card.configuration_status (PR #2756 chain).
+  // Workspace is reachable (heartbeating, /agent-card serves) but adapter.setup()
+  // failed — typically a missing/rotated LLM credential. Amber to differentiate from
+  // online (green) and failed (red) — the workspace itself is healthy, just needs
+  // configuration. Hover renders agent_card.configuration_error in the tooltip so
+  // the operator sees the exact env var to set.
+  not_configured: { dot: "bg-amber-300", glow: "shadow-amber-300/50", label: "Not configured", bar: "from-amber-400/20 to-transparent" },
 };

 export function statusDotClass(status: string): string {
@@ -0,0 +1,103 @@
+import { describe, it, expect } from "vitest";
+import {
+  getConfigurationStatus,
+  getConfigurationError,
+} from "../canvas-topology";
+
+// Tests for the getConfigurationStatus / getConfigurationError helpers
+// (issue #467 / PR #2756 chain). Surfacing the workspace's
+// `agent_card.configuration_status` is the user-visible payoff of
+// PR #2756's decoupling — without it, a misconfigured workspace looks
+// identical to a healthy one in the canvas tile.
+
+describe("getConfigurationStatus", () => {
+  it("returns null when agentCard is null", () => {
+    expect(getConfigurationStatus(null)).toBe(null);
+  });
+
+  it("returns null when agentCard has no configuration_status", () => {
+    expect(getConfigurationStatus({ name: "x" })).toBe(null);
+  });
+
+  it("returns 'ready' when agent reports configuration ok", () => {
+    expect(
+      getConfigurationStatus({ configuration_status: "ready" }),
+    ).toBe("ready");
+  });
+
+  it("returns 'not_configured' when agent reports setup failed", () => {
+    expect(
+      getConfigurationStatus({ configuration_status: "not_configured" }),
+    ).toBe("not_configured");
+  });
+
+  it("ignores unknown values defensively", () => {
+    // A future agent reporting a status string we don't yet recognise
+    // shouldn't crash the canvas — we treat it as 'no info' (null).
+    expect(
+      getConfigurationStatus({ configuration_status: "starting" }),
+    ).toBe(null);
+    expect(
+      getConfigurationStatus({ configuration_status: 42 }),
+    ).toBe(null);
+    expect(
+      getConfigurationStatus({ configuration_status: null }),
+    ).toBe(null);
+  });
+});
+
+describe("getConfigurationError", () => {
+  it("returns null when agentCard is null", () => {
+    expect(getConfigurationError(null)).toBe(null);
+  });
+
+  it("returns null when status is 'ready' even if error string present", () => {
+    // Defensive: if the agent somehow ships configuration_status=ready
+    // alongside a stale configuration_error from a previous boot, we
+    // trust the live status flag and don't surface the stale error.
+    expect(
+      getConfigurationError({
+        configuration_status: "ready",
+        configuration_error: "stale: was unset",
+      }),
+    ).toBe(null);
+  });
+
+  it("returns the error string when status is 'not_configured'", () => {
+    expect(
+      getConfigurationError({
+        configuration_status: "not_configured",
+        configuration_error:
+          "RuntimeError: Neither OPENAI_API_KEY nor MINIMAX_API_KEY is set",
+      }),
+    ).toBe(
+      "RuntimeError: Neither OPENAI_API_KEY nor MINIMAX_API_KEY is set",
+    );
+  });
+
+  it("returns null when status is 'not_configured' but error is missing", () => {
+    expect(
+      getConfigurationError({ configuration_status: "not_configured" }),
+    ).toBe(null);
+  });
+
+  it("returns null when error is empty string", () => {
+    // Empty string isn't actionable for the operator — treat same as
+    // missing.
+    expect(
+      getConfigurationError({
+        configuration_status: "not_configured",
+        configuration_error: "",
+      }),
+    ).toBe(null);
+  });
+
+  it("returns null when error is non-string", () => {
+    expect(
+      getConfigurationError({
+        configuration_status: "not_configured",
+        configuration_error: { reason: "object" },
+      }),
+    ).toBe(null);
+  });
+});
@@ -564,3 +564,42 @@ export function extractSkillNames(agentCard: Record<string, unknown> | null): st
    .map((skill: Record<string, unknown>) => String(skill.name || skill.id || ""))
    .filter(Boolean);
 }
+
+/**
+ * Returns the configuration status reported by the workspace, or null
+ * when the agent card doesn't carry one (older runtime, or pre-PR #2756
+ * worker).
+ *
+ * Pairs with molecule-core PR #2756: when adapter.setup() fails, the
+ * runtime mounts a not-configured handler AND advertises the failure
+ * via agent_card.configuration_status = "not_configured" +
+ * configuration_error = "<reason>". Canvas reads both to render a
+ * "needs config" tile instead of a confused "online but silent" state.
+ *
+ * Returns null (not undefined) so callers can distinguish "no info"
+ * from explicit values via a strict equality check.
+ */
+export function getConfigurationStatus(
+  agentCard: Record<string, unknown> | null,
+): "ready" | "not_configured" | null {
+  if (!agentCard) return null;
+  const raw = agentCard.configuration_status;
+  if (raw === "ready" || raw === "not_configured") return raw;
+  return null;
+}
+
+/**
+ * Returns the configuration error string from the agent card when
+ * configuration_status is "not_configured", or null otherwise.
+ *
+ * Already redacted server-side via secret_redactor (PR #2778) — safe to
+ * render in the UI verbatim.
+ */
+export function getConfigurationError(
+  agentCard: Record<string, unknown> | null,
+): string | null {
+  if (!agentCard) return null;
+  if (getConfigurationStatus(agentCard) !== "not_configured") return null;
+  const raw = agentCard.configuration_error;
+  return typeof raw === "string" && raw.length > 0 ? raw : null;
+}
@@ -27,11 +27,11 @@ prompt_files:
 # AGENTS.md-style example:
 #   prompt_files: [AGENTS.md]

-# Files to share with direct children (1-level inheritance)
-# Children fetch these at startup via GET /workspaces/:id/shared-context
-shared_context:
-  - architecture.md
-  - conventions.md
+# NOTE: `shared_context` (parent → child file injection at boot) was removed.
+# To share knowledge across a team, use memory v2's team:<id> namespace via
+# the recall_memory MCP tool — the agent pulls it on demand instead of
+# paying for it at every boot. For large blob-shaped artefacts, see RFC
+# #2789 (platform-owned shared file storage).

 # Skills to load -- folder names under skills/
 skills:
@@ -123,7 +123,6 @@ env:
 | `runtime` | No | Adapter to use: `langgraph` (default), `claude-code`, `crewai`, `autogen`, `deepagents`, `openclaw`. See [Agent Runtime Adapters](./cli-runtime.md). |
 | `model` | Yes | LangChain-compatible provider string (e.g. `anthropic:claude-sonnet-4-6`). Overridden by `MODEL_PROVIDER` env var if set. |
 | `prompt_files` | No | Ordered list of markdown files to load as system prompt. Defaults to `["system-prompt.md"]` if omitted. `MEMORY.md` and `USER.md` are auto-appended when present so frozen memory snapshots do not need to be duplicated here. Supports any agent framework's file structure (OpenClaw, Claude Code, etc.) |
-| `shared_context` | No | Files from this workspace's config dir to share with direct children. Children fetch these at startup and inject into their system prompt as `## Parent Context`. 1-level inheritance only (grandchildren don't see grandparent's context). |
 | `skills` | Yes | List of skill folder names to load from `skills/` |
 | `tools` | No | Built-in tools from workspace-template |
 | `memory` | No | Memory backend config (defaults to filesystem) |
@@ -157,7 +156,6 @@ The file watcher monitors the entire config directory. When `config.yaml` change
 | `name`, `description`, `version` | Yes | Rebuild Agent Card with new metadata |
 | `a2a` | **No** | Port and protocol changes require container restart |
 | `delegation` | Yes | Retry/timeout defaults take effect on next delegation call |
-| `shared_context` | Yes | Children fetch on next prompt rebuild; no restart needed |
 | `sub_workspaces` | **No** | Team structure changes go through `POST /workspaces/:id/expand` |

 See [Skills — Live Reload](./skills.md#live-reload) for the full file watcher flow.
@@ -24,21 +24,19 @@ When you receive a task, break it into sub-tasks and delegate to your team.
 Always review work before reporting completion to the caller.
 ```

-### 2. Parent Context (if child workspace)
+### 2. Team-shared knowledge (on demand)

-If this workspace was created via team expansion (has a `PARENT_ID` env var), it fetches its parent's shared context files at startup via `GET /workspaces/{parent_id}/shared-context`. The parent declares which files to share in its `config.yaml`:
+Team-scoped knowledge is no longer injected at boot. The previous
+`shared_context` field + `GET /workspaces/{parent_id}/shared-context`
+fetch was removed; agents now pull team-shared knowledge on demand via
+memory v2's `team:<id>` namespace using the `recall_memory` MCP tool.

-```yaml
-shared_context:
-  - architecture.md
-  - conventions.md
-```
-
-These files are injected as a `## Parent Context` section, with each file rendered under a `### {filename}` heading. This gives children the parent's project knowledge (architecture, conventions, API schemas) without exposing the parent's system prompt or full config.
-
-**1-level inheritance only:** A grandchild sees its direct parent's shared context, not its grandparent's. This mirrors the L2 Team Memory scope.
-
-**Graceful degradation:** If the parent is offline or the endpoint returns an error, the child starts normally without parent context.
+This shifts cost from "every boot, always" to "only when the agent
+asks", and lets team members write to the shared store from anywhere
+that can resolve the namespace (canvas Memory tab, agent
+`commit_memory`, admin import). For large blob-shaped artefacts (full
+architecture docs, brand assets, PDFs) see RFC #2789 (platform-owned
+shared file storage).

 ### 3. Skill Instructions

@@ -1,111 +0,0 @@
-# Team Expansion (Recursive Workspaces)
-
-When a workspace is expanded into a team, it gains sub-workspaces while its own agent remains as the **team lead** (coordinator). This is recursive — sub-workspaces can themselves be expanded into teams, infinitely deep.
-
-## How It Works
-
-When Developer PM is expanded into a team:
-
-```
-Business Core
-   |
-   +-- Developer PM (agent stays, becomes coordinator)
-          |
-          +-- Frontend Agent (sub-workspace, private scope)
-          +-- Backend Agent  (sub-workspace, private scope)
-          +-- QA Agent       (sub-workspace, private scope)
-```
-
- Developer PM's agent **still exists** and acts as coordinator
- Developer PM receives incoming A2A messages from Business Core
- Developer PM's agent decides how to delegate to sub-workspaces
- Sub-workspaces talk to Developer PM and to each other (same level)
- Sub-workspaces **cannot** talk to Business Core or any workspace outside the team
-
-## Communication Rules
-
-| Direction | Allowed? | Example |
-|-----------|----------|---------|
-| Parent level -> team lead | Yes | Business Core -> Developer PM |
-| Team lead -> sub-workspaces | Yes | Developer PM -> Frontend Agent |
-| Sub-workspace -> team lead | Yes | Frontend Agent -> Developer PM |
-| Sub-workspace <-> sibling | Yes | Frontend Agent <-> Backend Agent |
-| Outside -> sub-workspace directly | No (403) | Business Core -> Frontend Agent |
-| Sub-workspace -> outside directly | No | Frontend Agent -> Business Core |
-
-The team lead (Developer PM) is the **only** bridge between the team's internal world and the outside.
-
-## Scoped Registry
-
-Sub-workspaces register in the platform registry but with a **private scope**. The registry knows about them but enforces access control.
-
-```
-Registry:
-  Business Core      :8001   scope: public
-  Developer PM       :8002   scope: public
-  Frontend Agent     :8010   scope: private, parent=Developer PM
-  Backend Agent      :8011   scope: private, parent=Developer PM
-  QA Agent           :8012   scope: private, parent=Developer PM
-```
-
- The platform can always discover any workspace (for provisioning, monitoring)
- The parent workspace can discover its sub-workspaces
- Sub-workspaces can discover their siblings (same parent)
- Outside workspaces get a **403 Forbidden** if they try to discover a private sub-workspace
-
-## How to Expand
-
-Expansion is triggered via `POST /workspaces/:id/expand`. The platform reads the `sub_workspaces` list from the workspace's config and provisions each one. On the canvas, users right-click a workspace node and select "Expand into team."
-
-Collapsing is the inverse: `POST /workspaces/:id/collapse`. Sub-workspaces are stopped and removed.
-
-## What Happens on Expansion
-
-When Developer PM is expanded into a team, the hierarchy changes but the outside view doesn't. Business Core's parent/child relationship to Developer PM is unaffected — Developer PM still responds to the same A2A endpoint.
-
-The events fired:
- `WORKSPACE_EXPANDED` with the new `sub_workspace_ids` in the payload
- `WORKSPACE_PROVISIONING` for each new sub-workspace
- `WORKSPACE_ONLINE` for each sub-workspace as they come up
-
-Communication rules are automatically derived from the new hierarchy — no manual wiring needed.
-
-## Canvas Behavior
-
- Children render as embedded mini-cards (`TeamMemberChip`) inside the parent node, not as separate canvas nodes
- Each mini-card shows full status: gradient bar, name, tier badge, skills pills, active tasks, descendant count
- **Recursive rendering** up to 3 levels deep (`MAX_NESTING_DEPTH = 3`) — sub-cards can contain their own "Team" sections
- Parent node dynamically resizes: 210-280px (no children), 320-450px (children), 400-560px (grandchildren)
- Eject button (sky-blue arrow icon) on hover extracts a child from the team
- "Extract from Team" also available in the right-click context menu
- Double-click a team node to zoom/fit to the parent area
- The parent workspace node shows a badge with total descendant count
-
-## Collapsing a Team
-
-The inverse of expansion, triggered via `POST /workspaces/:id/collapse`:
-
-1. Each sub-workspace agent wraps up current work and writes a handoff document to memory
-2. Sub-workspaces are stopped and removed
-3. The team lead's agent goes back to handling everything directly
-4. A `WORKSPACE_COLLAPSED` event fires
-
-Sub-workspace memory is cleaned up based on backend (see [Memory — Cleanup](../architecture/memory.md#cleanup-on-workspace-deletion)).
-
-## Deleting a Team Workspace
-
-When a team workspace is deleted:
-1. Platform shows a warning listing all sub-workspaces that will be deleted
-2. User can **drag sub-workspaces out** of the team before confirming (promotes them to the parent level)
-3. On confirmation, cascade delete removes the parent and all remaining sub-workspaces
-4. `WORKSPACE_REMOVED` events fire for each deleted workspace
-
-## Related Docs
-
- [Communication Rules](../api-protocol/communication-rules.md) — Full access control model
- [Core Concepts](../product/core-concepts.md) — Workspace fundamentals
- [System Prompt Structure](./system-prompt-structure.md) — How peer capabilities are injected
- [Provisioner](../architecture/provisioner.md) — How sub-workspaces are deployed
- [Registry & Heartbeat](../api-protocol/registry-and-heartbeat.md) — How registration works
- [Event Log](../architecture/event-log.md) — Events fired during expansion
- [Canvas UI](../frontend/canvas.md) — Visual behavior of teams
@@ -0,0 +1,358 @@
+openapi: 3.0.3
+info:
+  title: Molecule Memory Plugin v1
+  version: 1.0.0
+  description: |
+    Contract between workspace-server and a memory backend plugin. The
+    plugin owns its own storage; workspace-server is the security
+    perimeter (secret redaction, namespace ACL, GLOBAL audit/wrap).
+
+    Defined in RFC #2728. See docs/rfc/memory-v2-rationale.md for design
+    rationale.
+
+    Auth: none. Plugins MUST be reachable only on a private network or
+    unix socket — workspace-server is the only sanctioned client.
+servers:
+  - url: http://localhost:9100
+    description: Built-in postgres-backed plugin (default)
+
+paths:
+  /v1/health:
+    get:
+      summary: Liveness + capability probe
+      operationId: getHealth
+      responses:
+        '200':
+          description: Plugin healthy
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/HealthResponse' }
+        '503':
+          description: Plugin unhealthy (e.g., backing store down)
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Error' }
+
+  /v1/namespaces/{name}:
+    parameters:
+      - $ref: '#/components/parameters/NamespaceName'
+    put:
+      summary: Upsert a namespace (idempotent)
+      operationId: upsertNamespace
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/NamespaceUpsert' }
+      responses:
+        '200': { $ref: '#/components/responses/Namespace' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+    patch:
+      summary: Update namespace metadata or TTL
+      operationId: patchNamespace
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/NamespacePatch' }
+      responses:
+        '200': { $ref: '#/components/responses/Namespace' }
+        '404': { $ref: '#/components/responses/NotFound' }
+    delete:
+      summary: Delete namespace and all its memories (operator action)
+      operationId: deleteNamespace
+      responses:
+        '204':
+          description: Deleted
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /v1/namespaces/{name}/memories:
+    parameters:
+      - $ref: '#/components/parameters/NamespaceName'
+    post:
+      summary: Write a memory to a namespace
+      description: |
+        `content` MUST already be secret-redacted by the workspace-server.
+        Plugin does not run additional redaction.
+      operationId: commitMemory
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/MemoryWrite' }
+      responses:
+        '201':
+          description: Memory persisted
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/MemoryWriteResponse' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+  /v1/search:
+    post:
+      summary: Search memories across one or more namespaces
+      description: |
+        workspace-server MUST intersect the requested `namespaces` with
+        the caller's currently-readable set BEFORE invoking this
+        endpoint. The plugin treats the list as authoritative.
+      operationId: searchMemories
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/SearchRequest' }
+      responses:
+        '200':
+          description: Search results
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/SearchResponse' }
+        '400': { $ref: '#/components/responses/BadRequest' }
+
+  /v1/memories/{id}:
+    parameters:
+      - in: path
+        name: id
+        required: true
+        schema: { type: string, format: uuid }
+    delete:
+      summary: Forget a memory by id
+      description: |
+        `requested_by_namespace` is the namespace the caller has write
+        access to; the plugin SHOULD reject if the memory doesn't belong
+        to that namespace.
+      operationId: forgetMemory
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ForgetRequest' }
+      responses:
+        '204':
+          description: Forgotten
+        '403': { $ref: '#/components/responses/Forbidden' }
+        '404': { $ref: '#/components/responses/NotFound' }
+
+components:
+  parameters:
+    NamespaceName:
+      in: path
+      name: name
+      required: true
+      schema:
+        type: string
+        minLength: 1
+        maxLength: 256
+        pattern: '^[a-z]+:[A-Za-z0-9_:.\-]+$'
+        example: 'workspace:550e8400-e29b-41d4-a716-446655440000'
+
+  responses:
+    Namespace:
+      description: Namespace state
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/Namespace' }
+    BadRequest:
+      description: Invalid input
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/Error' }
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/Error' }
+    Forbidden:
+      description: Caller lacks write access to the requested namespace
+      content:
+        application/json:
+          schema: { $ref: '#/components/schemas/Error' }
+
+  schemas:
+    HealthResponse:
+      type: object
+      required: [status, version, capabilities]
+      properties:
+        status: { type: string, enum: [ok, degraded] }
+        version: { type: string, example: "1.0.0" }
+        capabilities:
+          type: array
+          items:
+            type: string
+            enum: [embedding, fts, ttl, pin, propagation]
+          description: |
+            Optional features this plugin supports. workspace-server
+            adapts MCP responses based on this list (e.g., agents can
+            request semantic search only when `embedding` is present).
+
+    NamespaceKind:
+      type: string
+      enum: [workspace, team, org, custom]
+
+    Namespace:
+      type: object
+      required: [name, kind, created_at]
+      properties:
+        name: { type: string }
+        kind: { $ref: '#/components/schemas/NamespaceKind' }
+        expires_at:
+          type: string
+          format: date-time
+          nullable: true
+        metadata:
+          type: object
+          additionalProperties: true
+          nullable: true
+        created_at: { type: string, format: date-time }
+
+    NamespaceUpsert:
+      type: object
+      required: [kind]
+      properties:
+        kind: { $ref: '#/components/schemas/NamespaceKind' }
+        expires_at: { type: string, format: date-time, nullable: true }
+        metadata:
+          type: object
+          additionalProperties: true
+          nullable: true
+
+    NamespacePatch:
+      type: object
+      properties:
+        expires_at: { type: string, format: date-time, nullable: true }
+        metadata:
+          type: object
+          additionalProperties: true
+          nullable: true
+
+    MemoryKind:
+      type: string
+      enum: [fact, summary, checkpoint]
+
+    MemorySource:
+      type: string
+      enum: [agent, runtime, user]
+
+    MemoryWrite:
+      type: object
+      required: [content, kind, source]
+      properties:
+        id:
+          type: string
+          format: uuid
+          nullable: true
+          description: |
+            Optional idempotency key. When supplied, the plugin MUST
+            treat the write as upsert keyed on this id (re-running
+            the same write does not duplicate). When omitted, the
+            plugin generates a fresh UUID. Used by the backfill CLI.
+        content:
+          type: string
+          minLength: 1
+          description: Already secret-redacted by workspace-server.
+        kind: { $ref: '#/components/schemas/MemoryKind' }
+        source: { $ref: '#/components/schemas/MemorySource' }
+        expires_at: { type: string, format: date-time, nullable: true }
+        propagation:
+          type: object
+          additionalProperties: true
+          nullable: true
+          description: |
+            Opaque metadata the plugin stores and returns. Reserved for
+            future cross-namespace propagation semantics.
+        pin: { type: boolean, default: false }
+        embedding:
+          type: array
+          items: { type: number }
+          nullable: true
+          description: |
+            Optional pre-computed embedding. Plugins reporting the
+            `embedding` capability MAY ignore this and recompute.
+
+    MemoryWriteResponse:
+      type: object
+      required: [id, namespace]
+      properties:
+        id: { type: string, format: uuid }
+        namespace: { type: string }
+
+    Memory:
+      type: object
+      required: [id, namespace, content, kind, source, created_at]
+      properties:
+        id: { type: string, format: uuid }
+        namespace: { type: string }
+        content: { type: string }
+        kind: { $ref: '#/components/schemas/MemoryKind' }
+        source: { $ref: '#/components/schemas/MemorySource' }
+        expires_at: { type: string, format: date-time, nullable: true }
+        propagation:
+          type: object
+          additionalProperties: true
+          nullable: true
+        pin: { type: boolean }
+        created_at: { type: string, format: date-time }
+        score:
+          type: number
+          nullable: true
+          description: Relevance score from search (semantic + FTS).
+
+    SearchRequest:
+      type: object
+      required: [namespaces]
+      properties:
+        namespaces:
+          type: array
+          items: { type: string }
+          minItems: 1
+          description: |
+            Already intersected with the caller's readable set by
+            workspace-server.
+        query: { type: string }
+        kinds:
+          type: array
+          items: { $ref: '#/components/schemas/MemoryKind' }
+        limit:
+          type: integer
+          minimum: 1
+          maximum: 100
+          default: 20
+        embedding:
+          type: array
+          items: { type: number }
+          nullable: true
+
+    SearchResponse:
+      type: object
+      required: [memories]
+      properties:
+        memories:
+          type: array
+          items: { $ref: '#/components/schemas/Memory' }
+
+    ForgetRequest:
+      type: object
+      required: [requested_by_namespace]
+      properties:
+        requested_by_namespace:
+          type: string
+          description: Namespace the caller has write access to.
+
+    Error:
+      type: object
+      required: [code, message]
+      properties:
+        code:
+          type: string
+          enum:
+            - bad_request
+            - not_found
+            - forbidden
+            - internal
+            - unavailable
+        message: { type: string }
+        details:
+          type: object
+          additionalProperties: true
+          nullable: true
@@ -199,7 +199,6 @@ Install safeguards bound the cost of a single install (env-tunable via `PLUGIN_I
 | `GET` | `/templates` | List available templates. **Requires AdminAuth** (PR #701). |
 | `GET` | `/org/templates` | List available org templates. **Requires AdminAuth** (PR #701). |
 | `POST` | `/templates/import` | Import an agent folder as a new template |
-| `GET` | `/workspaces/:id/shared-context` | Read parent shared-context files |
 | `GET` | `/workspaces/:id/files` | List files under an allowed root |
 | `GET` | `/workspaces/:id/files/*path` | Read a file |
 | `PUT` | `/workspaces/:id/files/*path` | Write a file |
@@ -41,8 +41,6 @@ Full contract: `docs/runbooks/admin-auth.md`.
 | GET | /admin/workspaces/:id/test-token | admin_test_token.go — mint a fresh bearer token for E2E scripts; returns 404 unless `MOLECULE_ENV != production` or `MOLECULE_ENABLE_TEST_TOKENS=1` |
 | GET/POST/DELETE | /admin/secrets[/:key] | secrets.go — legacy aliases for /settings/secrets |
 | WS | /workspaces/:id/terminal | terminal.go |
-| POST | /workspaces/:id/expand | team.go |
-| POST | /workspaces/:id/collapse | team.go |
 | POST/GET | /workspaces/:id/approvals | approvals.go |
 | POST | /workspaces/:id/approvals/:id/decide | approvals.go |
 | GET | /approvals/pending | approvals.go |
@@ -68,7 +66,6 @@ Full contract: `docs/runbooks/admin-auth.md`.
 | GET | /channels/adapters | channels.go (list available platforms) |
 | POST | /channels/discover | channels.go (auto-detect chats for a bot token) |
 | POST | /webhooks/:type | channels.go (incoming social webhook) |
-| GET | /workspaces/:id/shared-context | templates.go |
 | GET/PUT/DELETE | /workspaces/:id/files[/*path] | templates.go |
 | GET | /canvas/viewport | viewport.go — open, no auth required (cosmetic, bootstrap-friendly) |
 | PUT | /canvas/viewport | viewport.go — `CanvasOrBearer` middleware; accepts bearer OR Origin matching `CORS_ORIGINS`. Cosmetic-only route — worst case viewport corruption, recovered by page refresh. |
@@ -2,7 +2,7 @@

 **Status:** living document — update when you ship a feature that touches one backend.
 **Owner:** workspace-server + controlplane teams.
-**Last audit:** 2026-05-02 (Claude agent, PR #TBD).
+**Last audit:** 2026-05-05 (Claude agent — `provisionWorkspaceAuto` / `StopWorkspaceAuto` / `HasProvisioner` SoT pattern landed in PRs #2811 + #2824).

 ## Why this exists

@@ -15,16 +15,39 @@ Every user-visible workspace feature should work on both backends unless it is f

 This document is the canonical matrix. If you are landing a workspace-facing feature, update the row before you merge.

+## How to dispatch (the SoT pattern)
+
+When a handler needs to start, stop, or check whether-something-can-run a workspace, it MUST go through the centralized dispatcher on `WorkspaceHandler`:
+
+| Need | Use | Source |
+|---|---|---|
+| Start a workspace | `provisionWorkspaceAuto(ctx, ...)` | `workspace.go:130` |
+| Stop a workspace | `StopWorkspaceAuto(ctx, wsID)` | `workspace.go:172` |
+| Gate "do we have any backend wired?" | `HasProvisioner()` | `workspace.go:115` |
+
+Each dispatcher routes to `cpProv.X()` when the SaaS backend is wired, then `provisioner.X()` when the Docker backend is wired, then a defined fallback (`provisionWorkspaceAuto` self-marks-failed; `StopWorkspaceAuto` no-ops; `HasProvisioner` returns false).
+
+**Rule: do not call `h.cpProv.Stop`, `h.provisioner.Stop`, `h.cpProv.Start`, or `h.provisioner.Start` directly from a handler.** Source-level pins (`TestNoCallSiteCallsDirectProvisionerExceptAuto`, `TestNoCallSiteCallsBareStop`) gate this at CI; they exist because the same drift class shipped twice — TeamHandler.Expand (#2367) bypassed routing on Start, then `team.go:208` + `workspace_crud.go:432` bypassed it on Stop (#2813, #2814) for ~6 months.
+
+Allowed exceptions (in the source-pin allowlists):
+- `workspace.go` and `workspace_provision.go` — define the per-backend bodies the dispatcher routes between.
+- `workspace_restart.go` — pre-dates the dispatchers and uses manual if-cpProv-else dispatch with retry semantics tuned for the restart hot path. Consolidation tracked in #2799.
+- `container_files.go` — drives the Docker daemon directly for short-lived file-copy containers; no workspace-level Stop semantics involved.
+
+For "do we have any backend?", use `HasProvisioner()`, never bare `h.provisioner == nil && h.cpProv == nil`. Source-level pin `TestNoBareBothNilCheck` enforces this — added 2026-05-05 after the hongming org-import incident showed the bare check shape was a recurring drift target.
+
 ## The matrix

 | Feature | File(s) | Docker | EC2 | Verdict |
 |---|---|---|---|---|
 | **Lifecycle** | | | | |
-| Create | `workspace_provision.go:19-214` | `provisionWorkspace()` → `provisioner.Start()` | `provisionWorkspaceCP()` → `cpProv.Start()` | ✅ parity |
+| Create | `workspace.go:130` `provisionWorkspaceAuto` → `provisionWorkspace()` (Docker) / `provisionWorkspaceCP()` (CP) | dispatched | dispatched | ✅ parity (single source of truth, PR #2811) |
 | Start | `provisioner.go:140-325` | container create + image pull | EC2 `RunInstance` via CP | ✅ parity |
-| Stop | `provisioner.go:772-785` | `ContainerRemove(force=true)` + optional volume rm | `DELETE /cp/workspaces/:id` | ✅ parity |
+| Stop | `workspace.go:172` `StopWorkspaceAuto` → `provisioner.Stop()` (Docker) / `cpProv.Stop()` (CP) | dispatched | dispatched | ✅ parity (single source of truth, PR #2824) |
 | Restart | `workspace_restart.go:45-210` | reads runtime from live container before stop | reads runtime from DB only | ⚠️ divergent — config-change + crash window can boot old runtime on EC2 |
-| Delete | `workspace_crud.go` | stop + volume rm | stop only (stateless) | ✅ parity (expected divergence on volume cleanup) |
+| Delete | `workspace_crud.go` `stopAndRemove` → `StopWorkspaceAuto` + Docker-only `RemoveVolume` | stop + volume rm | stop only (stateless — CP has no volumes) | ✅ parity (PR #2824 closed the SaaS-leak gap) |
+| Org-import (bulk Create) | `org_import.go:178` gates on `h.workspace.HasProvisioner()`; routes through `provisionWorkspaceAuto` per workspace | dispatched | dispatched | ✅ parity (PR #2811 closed the SaaS-skip gate) |
+| Team-collapse (bulk Stop) | `team.go:206` calls `StopWorkspaceAuto` for each child | dispatched | dispatched | ✅ parity (PR #2824 closed the SaaS-leak gap) |
 | **Secrets** | | | | |
 | Create / update | `secrets.go` | DB insert, injected at container start | DB insert, injected via user-data at boot | ✅ parity |
 | Redaction | `workspace_provision.go:251` | applied at memory-seed time | applied at agent runtime | ⚠️ divergent — timing differs |
@@ -76,7 +99,23 @@ This document is the canonical matrix. If you are landing a workspace-facing fea

 - **`tools/check-template-parity.sh`** (this repo) — ensures `install.sh` and `start.sh` in a template repo forward identical sets of provider keys. Wire into each template repo's CI as `bash $MONOREPO/tools/check-template-parity.sh install.sh start.sh`.
 - **Contract tests** (stub) — `workspace-server/internal/provisioner/backend_contract_test.go` defines the behaviors every `provisioner.Provisioner` implementation must satisfy. Fails compile when a method drifts between `Docker` and `CPProvisioner`. Scenario-level runs are `t.Skip`'d today pending drift risk #6 (see above) — compile-time assertions still catch method drift.
+- **Source-level dispatcher pins** — `workspace_provision_auto_test.go` enforces the SoT pattern documented above:
+  - `TestNoCallSiteCallsDirectProvisionerExceptAuto` — no handler calls `.provisionWorkspace(` or `.provisionWorkspaceCP(` directly outside the dispatcher's allowlist.
+  - `TestNoCallSiteCallsBareStop` — no handler calls `.provisioner.Stop(` or `.cpProv.Stop(` directly outside the dispatcher's allowlist (strips Go comments before substring match so archaeology in code comments doesn't trip the gate).
+  - `TestNoBareBothNilCheck` — no production code uses `h.provisioner == nil && h.cpProv == nil`; must use `!h.HasProvisioner()`.
+  - `TestOrgImportGate_UsesHasProvisionerNotBareField` — pins the org-import provisioning gate against the bare-Docker-check shape that caused the 2026-05-05 hongming incident.

 ## How to update this doc

 When you land a feature that touches a handler dispatch on `h.cpProv != nil`, add or update the matching row. If you can't implement both backends in the same PR, mark the row `docker-only` or `ec2-only` and file an issue tracking the gap.
+
+### When you add a NEW dispatch site
+
+If you find yourself writing `if h.cpProv != nil { ... } else if h.provisioner != nil { ... }` for a new operation (Pause, Hibernate, Snapshot, etc.):
+
+1. Add a `<Op>WorkspaceAuto` method on `WorkspaceHandler` next to the existing dispatchers. Mirror the docstring shape: routing, no-backend fallback, ordering rationale.
+2. Add a source-level pin in `workspace_provision_auto_test.go` — the bare-call shape your dispatcher replaces, fail when a handler reintroduces it.
+3. Add a row to the matrix above with the dispatcher reference.
+4. If your operation has retry semantics specific to a hot path, leave them in the original location for now and file a follow-up under #2799 — don't bake retry into the generic dispatcher unless every caller benefits.
+
+The pattern is "one dispatcher per verb." Don't fold every operation into `provisionWorkspaceAuto` — different verbs have different no-backend fallbacks (mark-failed for Start, no-op for Stop, false for Has).
@@ -336,8 +336,6 @@ This same logic governs: A2A delegation, memory scope enforcement, activity visi

 | Method | Endpoint | Purpose |
 |--------|----------|---------|
-| `POST` | `/workspaces/:id/expand` | Expand workspace into team (become coordinator) |
-| `POST` | `/workspaces/:id/collapse` | Collapse team back to single workspace |

 ### Files, Terminal, Templates, Bundles (8 endpoints)

@@ -523,7 +521,8 @@ runtime_config:                            # Runtime-specific settings
 skills: ["skill1", "skill2"]               # Folder names under skills/
 tools: ["web_search", "filesystem"]        # Built-in tool names
 prompt_files: ["system-prompt.md"]         # Additional prompt text files
-shared_context: []                         # Files from parent workspace
+# `shared_context` was removed; team-shared knowledge now lives in memory v2's
+# team:<id> namespace (recall_memory MCP tool). See RFC #2789 for shared files.

 a2a:
  port: 8000
@@ -0,0 +1,58 @@
+# E2E coverage matrix
+
+This document is the source of truth for which E2E suites guard which surfaces and which gates are wired up where. Read this before adding a new E2E or moving a check between branches.
+
+## Suites
+
+| Workflow file | Job (= required-check name) | What it covers | Cron |
+|---|---|---|---|
+| `e2e-api.yml` | `E2E API Smoke Test` | A2A handshake, registry/register, /workspaces/:id/a2a forward, structured-event emission. Lightweight enough to run on every PR. | — |
+| `e2e-staging-canvas.yml` | `Canvas tabs E2E` | Canvas-tab Playwright UX checks against staging — config tab, secrets tab, agent-card tab, Activity hydration. | weekly Sun 08:00 UTC |
+| `e2e-staging-saas.yml` | `E2E Staging SaaS` | Full lifecycle: org creation → workspace provision (CP path) → A2A delegation → status/heartbeat → workspace delete → EC2 termination. The integration test that catches the silent-drop bug class (#2486 / #2811 / #2813 / #2814). | daily 07:00 UTC |
+| `e2e-staging-external.yml` | `E2E Staging External Runtime` | External-runtime registration + heartbeat staleness sweep + `/registry/peers` resolution. Validates the OSS-templated workspace path. | daily 07:30 UTC |
+| `e2e-staging-sanity.yml` | `Intentional-failure teardown sanity` | Inverted assertion — the run MUST fail. Validates the leak-detection self-check itself; not for general gating. | weekly Mon 06:00 UTC |
+| `continuous-synth-e2e.yml` | `Synthetic E2E against staging` | Standing background coverage between PR runs. Catches drift in production-like staging that PR-time E2Es miss. | every 15 min |
+
+## Required-check status (branch protection)
+
+| Suite | staging required | main required |
+|---|---|---|
+| `E2E API Smoke Test` | ✅ this PR | ✅ |
+| `Canvas tabs E2E` | ✅ this PR | (see follow-up) |
+| `E2E Staging SaaS` | ❌ — needs always-emit refactor | ❌ |
+| `E2E Staging External Runtime` | ❌ — needs always-emit refactor | ❌ |
+| `Intentional-failure teardown sanity` | ❌ inverted assertion, never required | ❌ |
+| `Synthetic E2E against staging` | ❌ cron-only, not a per-PR gate | ❌ |
+
+## Why the always-emit pattern matters
+
+Branch protection requires a *check name* to land at SUCCESS for every PR. Workflows with `paths:` filters that exclude a PR never run, so the check name never appears, and the PR sits BLOCKED forever.
+
+The pattern that supports being required is:
+
+1. Workflow always triggers on push/PR to the protected branch.
+2. A `detect-changes` job uses `dorny/paths-filter` to decide if real work runs.
+3. The protected job runs unconditionally and either (a) does real work when paths matched, or (b) emits a no-op SUCCESS step when paths skipped.
+
+`e2e-api.yml` and `e2e-staging-canvas.yml` already have this shape. `e2e-staging-saas.yml` and `e2e-staging-external.yml` use plain `paths:` filters and need the refactor before they can be required (filed as follow-up).
+
+## Adding a new E2E suite
+
+1. Pick a verb: smoke test, full lifecycle, fault-injection, drift detection. Pre-existing suites split along these lines.
+2. Use the always-emit shape so the check name can be made required.
+3. Add a row to the matrix above.
+4. Decide cron cadence based on cost + how fast drift would otherwise be caught.
+5. If you want it required, add to the relevant branch protection via `tools/branch-protection/apply.sh` (this PR adds the script).
+
+## When to break glass — temporarily skip a required E2E
+
+Don't. If an E2E is intermittently flaky, fix the test or move it out of required. The point of a required check is that it's load-bearing; bypassing one with admin override teaches the next operator the gate is optional.
+
+If a Production incident requires bypassing, document the override in the incident postmortem with a same-week followup to either fix the test or rip the check out of required.
+
+## Related issues / PRs
+
+- #2486 — silent-drop bug class that the SaaS E2E now catches
+- PR #2811 — `provisionWorkspaceAuto` consolidation (org-import SaaS gate)
+- PR #2824 — `StopWorkspaceAuto` mirror (closes #2813 + #2814)
+- Follow-up: refactor `e2e-staging-saas` + `e2e-staging-external` to always-emit (so they can be required)
@@ -186,4 +186,3 @@ So the UI now exposes more operational failure state directly instead of silentl
 - [Quickstart](../quickstart.md)
 - [Platform API](../api-protocol/platform-api.md)
 - [Workspace Runtime](../agent-runtime/workspace-runtime.md)
- [Team Expansion](../agent-runtime/team-expansion.md)
@@ -18,7 +18,7 @@ lands in the watch list with a colliding term, add a row here.
 | **plugin** | A directory under `plugins/` packaging one or more skills or an MCP server wrapper, installable per-workspace via `POST /workspaces/:id/plugins`. Governed by `plugin.yaml`. | **Langflow**: a visual UI node / component in a flowchart. **CrewAI**: a Python-importable callable registered as a capability. |
 | **agent** | A persistent containerized workspace running continuously — an identity with memory, a role, and a schedule. Not a one-shot invocation. | Most frameworks (AutoGPT, LangChain agents, OpenAI Assistants): a stateless function-call loop. No persistence between invocations unless explicitly checkpointed. |
 | **flow** | A task execution within a workspace — a request enters, the agent runs tools, emits a response, logs activity. No explicit graph abstraction. | **Langflow**: a directed graph of nodes you author visually. **LangGraph**: a stateful graph of callable nodes. Our "flow" is an imperative timeline, not a graph. |
-| **team** | A named cluster of workspaces under a PM (org template `expand_team`). Used for role grouping in Canvas. | **CrewAI**: a "crew" is a sequence of agents that pass a task through a declared order. Our "team" is an org-chart abstraction, not an execution order. |
+| **team** | A named cluster of workspaces under a PM . Used for role grouping in Canvas. | **CrewAI**: a "crew" is a sequence of agents that pass a task through a declared order. Our "team" is an org-chart abstraction, not an execution order. |
 | **skill** | A directory with `SKILL.md` that an agent invokes via the `Skill` tool. Skills are documentation + optional scripts that teach an agent a recipe. | **Anthropic Skills API**: nearly identical. **CrewAI tool**: closer to our plugin's MCP tool, not our skill. |
 | **channel** | An outbound/inbound social integration (Telegram, Slack, …) per-workspace, wired in `workspace_channels`. | Slack's "channel": the container for messages. We use "channel" for the adapter + credentials, not the conversation itself. |
 | **runtime** | The execution engine image tag for a workspace: one of `langgraph`, `claude-code`, `openclaw`, `crewai`, `autogen`, `deepagents`, `hermes`. | **LangGraph runtime**: the Python process running the graph. We use "runtime" for the Docker image + adapter pairing, not the inner process. |
@@ -166,8 +166,6 @@ list_workspaces

 | MCP Tool | API Route | Method | Description |
 |----------|-----------|--------|-------------|
-| `expand_team` | `/workspaces/:id/expand` | POST | Expand team node |
-| `collapse_team` | `/workspaces/:id/collapse` | POST | Collapse team node |

 ### Templates & Bundles

@@ -0,0 +1,113 @@
+# Memory Plugin Contract — Changelog
+
+Every breaking or operationally-relevant change to the v1 plugin
+contract or the workspace-server-side wiring lands here. Plugin
+authors should subscribe to PRs touching this file.
+
+## [Unreleased] — fixup wave 1 (post-RFC-#2728 self-review)
+
+A self-review of the initial 11-PR rollout (PRs #2729-#2742) flagged
+two correctness bugs and three operational hazards. This wave fixes
+all of them. Order matches operator-impact severity.
+
+### Critical: backfill idempotency via `MemoryWrite.id` (#2744)
+
+**The bug.** The backfill CLI claimed idempotent on re-run, but
+`gen_random_uuid()` in the plugin's INSERT meant every retry created
+a fresh row. Operators retrying a failed `-apply` would silently
+double their memory count.
+
+**The fix.** Optional `id` field on `MemoryWrite`. When supplied,
+plugins MUST upsert. The backfill now forwards `agent_memories.id`
+to `MemoryWrite.id`, so retries update in place.
+
+**Plugin author action.** If your plugin uses
+`INSERT INTO ... DEFAULT gen_random_uuid()`, switch to
+`INSERT ... ON CONFLICT (id) DO UPDATE` when `id` is set. The wire
+contract is forward-compatible — plugins that ignore the field still
+work for production agent commits (which leave `id` empty), but they
+will silently corrupt backfill retries.
+
+### Critical: `memory-backfill -verify` mode (#2747)
+
+**The miss.** The original PR-7 task spec called for a parity-check
+mode but it never landed. Operators had no way to confirm a
+migration succeeded short of "no errors logged."
+
+**The fix.** New `-verify` flag samples N workspaces, queries
+`agent_memories` direct, runs an equivalent plugin search via the
+namespace resolver, multiset-compares contents. Reports mismatches
+to stdout and exits non-zero so CI can gate the cutover.
+
+```bash
+memory-backfill -verify                        # default sample 50
+memory-backfill -verify -verify-sample=200     # bigger
+memory-backfill -verify -workspace=<uuid>      # one workspace
+```
+
+### Important: `expires_at` validation (#2746)
+
+**The bug.** `commit_memory_v2` silently dropped malformed
+`expires_at` strings. Agent passes `expires_at: "tomorrow"`, gets a
+200, memory has no TTL — agent thinks it set a TTL, didn't.
+
+**The fix.** Returns
+`fmt.Errorf("invalid expires_at: must be RFC3339")` on parse
+failure. Plugin is not called in this case.
+
+**Plugin author action.** None — this is a workspace-server-side
+fix. But: if your plugin advertises the `ttl` capability, make sure
+you actually evict expired rows on read (not just on a janitor cron
+that runs once a day). The harness in `testing-your-plugin.md` has
+a TTL-eviction test you should run.
+
+### Important: audit log JSON via `json.Marshal` (#2746)
+
+**The bug.** `auditOrgWrite` built `activity_logs.metadata` via
+`fmt.Sprintf` with `%q`. For ASCII (today's UUID + hex digest) this
+coincidentally produces valid JSON; for unicode or control bytes it
+silently produces non-JSON.
+
+**The fix.** Replaced with `json.Marshal(map[string]string{...})`.
+Same wire shape today, won't regress when metadata grows.
+
+**Plugin author action.** None — workspace-server-internal.
+
+### Operator action: staging verification (#292)
+
+**Status.** Tracked as task #292. PR-merged ≠ verified. Operator
+must:
+1. Provision a staging tenant, set `MEMORY_PLUGIN_URL`
+2. Run real `commit_memory_v2` from a workspace
+3. `memory-backfill -dry-run` against staging data
+4. `memory-backfill -apply`, then `-verify`
+5. Set `MEMORY_V2_CUTOVER=true`, verify admin export still works
+6. Run a legacy `commit_memory` from a workspace, verify it lands
+   in plugin storage via the PR-6 shim
+
+### Other follow-ups still open
+
+- **#289**: admin export O(workspaces) → O(namespaces) — N+1 pattern
+  in `exportViaPlugin` (1000-workspace tenants run 1000× resolver
+  CTEs + 1000× plugin searches today).
+- **#291**: workspace deletion must call `DELETE
+  /v1/namespaces/{name}` — orphans accumulate today.
+- **#293**: real-subprocess boot E2E — current PR-11 is integration
+  (httptest + sqlmock), not E2E.
+
+These are tracked but deferred; they're operationally annoying, not
+incident-shaped.
+
+## [v1.0.0] — initial release (RFC #2728, PRs #2729-#2742)
+
+Initial plugin contract + 11-PR rollout. See
+[issue #2728](https://github.com/Molecule-AI/molecule-core/issues/2728)
+for the full RFC.
+
+Endpoints: `/v1/health`, `/v1/namespaces/{name}` (PUT/PATCH/DELETE),
+`/v1/namespaces/{name}/memories` (POST), `/v1/search` (POST),
+`/v1/memories/{id}` (DELETE).
+
+Capabilities: `embedding`, `fts`, `ttl`, `pin`, `propagation`.
+
+Operator runbook: see [README.md § Replacing the built-in plugin](README.md#replacing-the-built-in-plugin).
@@ -0,0 +1,191 @@
+# Writing a Memory Plugin
+
+This document is for operators and ecosystem authors who want to
+replace the built-in postgres-backed memory plugin (the default
+implementation that ships with workspace-server) with their own.
+
+The contract was introduced by RFC #2728. The shipped binary is
+`cmd/memory-plugin-postgres/`; reading its source is the fastest way
+to see a complete reference implementation.
+
+## What the contract is
+
+The plugin is an HTTP server that workspace-server talks to via the
+OpenAPI v1 spec at [`docs/api-protocol/memory-plugin-v1.yaml`](../api-protocol/memory-plugin-v1.yaml).
+
+Six endpoints:
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/v1/health` | GET | Liveness probe + capability list |
+| `/v1/namespaces/{name}` | PUT | Idempotent upsert |
+| `/v1/namespaces/{name}` | PATCH | Update TTL or metadata |
+| `/v1/namespaces/{name}` | DELETE | Remove namespace and its memories |
+| `/v1/namespaces/{name}/memories` | POST | Write a memory |
+| `/v1/search` | POST | Multi-namespace search |
+| `/v1/memories/{id}` | DELETE | Forget a memory |
+
+The wire types are defined in
+`workspace-server/internal/memory/contract/contract.go`. Run-time
+validation is built into the Go bindings via `Validate()` methods —
+your plugin SHOULD perform equivalent validation.
+
+## What workspace-server takes care of
+
+You do **not** implement these in the plugin; workspace-server is the
+security perimeter:
+
+- **Secret redaction** (SAFE-T1201). All `content` you receive is
+  already scrubbed. Don't run additional redaction; it's pointless.
+- **Namespace ACL**. workspace-server intersects the caller's
+  readable namespaces against the requested list before sending you
+  the search request. The list you receive is authoritative.
+- **GLOBAL audit**. Org-namespace writes are recorded in
+  `activity_logs` server-side; you don't see them.
+- **Prompt-injection wrap**. Org memories returned to agents get a
+  `[MEMORY id=... scope=ORG ns=...]:` prefix added at the
+  workspace-server layer. Your `content` field is plain text.
+
+## What you implement
+
+- Storage of `memory_namespaces` and `memory_records` (or whatever
+  shape you want — Pinecone vectors, an in-memory map, etc.)
+- The 7 endpoints above with the request/response shapes the spec
+  defines
+- `/v1/health` reporting your supported capabilities (see below)
+- Idempotency on namespace upsert (PUT semantics, not POST)
+- Idempotency on memory commit when `MemoryWrite.id` is supplied
+  (see "Memory idempotency" below)
+
+## Memory idempotency
+
+`MemoryWrite.id` is optional. Two contracts to honor:
+
+| Caller passes | Plugin MUST |
+|---|---|
+| `id` omitted | Generate a fresh UUID, return it in the response |
+| `id` set | Upsert keyed on this id — if a row with that id already exists, UPDATE it in place rather than inserting a duplicate |
+
+The backfill CLI (`memory-backfill`) relies on the upsert behavior
+so retries don't duplicate rows. Production agent commits leave `id`
+empty and rely on the plugin's UUID generator — the hot path is
+unchanged.
+
+The built-in postgres plugin implements this with `INSERT ... ON
+CONFLICT (id) DO UPDATE`. A vector-DB plugin (e.g., Pinecone) would
+use the database's native upsert primitive on the same id.
+
+## Capability negotiation
+
+Your `/v1/health` response declares what features you support:
+
+```json
+{
+  "status": "ok",
+  "version": "1.0.0",
+  "capabilities": ["embedding", "fts", "ttl", "pin", "propagation"]
+}
+```
+
+| Capability | What it gates |
+|---|---|
+| `embedding` | Agents may ask for semantic search; you receive `embedding: [...]` in search bodies |
+| `fts` | Agents may pass a query string; you decide how to match (FTS, ILIKE, regex) |
+| `ttl` | Agents may set `expires_at`; you must not return expired rows |
+| `pin` | Agents may set `pin: true`; you should rank pinned rows first |
+| `propagation` | Agents may set `propagation: {...}`; you must store it as opaque JSON and return it on read |
+
+A capability you DON'T list is fine — workspace-server adapts the MCP
+tool surface to match. E.g., a Pinecone-only plugin that lists only
+`embedding` will silently ignore agents' `query` strings.
+
+## Deployment models
+
+Three common shapes:
+
+1. **Same machine, different process**: workspace-server boots, then
+   `MEMORY_PLUGIN_URL=http://localhost:9100` points at your plugin
+   running on a unix socket or localhost port. This is what the
+   built-in postgres plugin does.
+
+2. **Separate container**: deploy your plugin as its own service on
+   the private network. Set `MEMORY_PLUGIN_URL` to its DNS name.
+
+3. **Self-managed**: customer-owned plugin running on customer-owned
+   infrastructure, accessed over a tunnel. Same env-var wiring.
+
+Auth is **none** — the plugin must be reachable only on a private
+network. workspace-server is the only sanctioned client.
+
+## Replacing the built-in plugin
+
+This is the canonical operator runbook for swapping the default
+plugin out. The same sequence applies whether you're swapping for
+another postgres plugin variant, Pinecone, Letta, or a custom
+implementation.
+
+1. **Stand up the new plugin.** Deploy the binary/container, confirm
+   it boots, confirm `/v1/health` returns `ok` with the capability
+   list you expect.
+
+2. **Run the backfill in dry-run mode** to scope the migration:
+   ```bash
+   DATABASE_URL=postgres://... \
+   MEMORY_PLUGIN_URL=http://your-plugin:9100 \
+   memory-backfill -dry-run
+   ```
+   Reports row count + namespace mapping per workspace, no writes.
+
+3. **Apply the backfill:**
+   ```bash
+   memory-backfill -apply
+   ```
+   Idempotent on retry — the backfill passes each `agent_memories.id`
+   to `MemoryWrite.id`, so partial-then-full re-runs upsert in place.
+
+4. **Verify parity** before flipping the cutover flag:
+   ```bash
+   memory-backfill -verify -verify-sample=200
+   ```
+   Random-samples N workspaces, diffs `agent_memories` direct query
+   against plugin search via the workspace's readable namespaces.
+   Reports mismatches and exits non-zero if any are found — wire
+   into your CI to gate the cutover.
+
+5. **Flip the cutover flag.** Set `MEMORY_V2_CUTOVER=true` on
+   workspace-server and restart. Admin export/import now route
+   through the plugin; legacy `agent_memories` becomes read-only.
+
+6. **Existing data in the old plugin's tables is NOT auto-dropped.**
+   Deliberate safety property — operator drops manually after the
+   ~60-day grace window. If you switch back later, old data comes
+   back into use (no loss).
+
+If `-verify` reports mismatches, do NOT set `MEMORY_V2_CUTOVER` —
+inspect the output, re-run `-apply` to backfill missing rows (it
+upserts, so this is safe), and re-verify.
+
+## Worked examples
+
+- [`pinecone-example/`](pinecone-example/) — full Pinecone-backed plugin
+- [`testing-your-plugin.md`](testing-your-plugin.md) — running the
+  contract test harness against your implementation
+
+## When to write one vs. fork the default
+
+Fork the default postgres plugin if:
+- You want different SQL (Materialized views? Different vector index?)
+- You want extra auth on top
+- You want server-side metrics emission
+
+Write a fresh plugin if:
+- The storage backend is fundamentally different (vector DB, KV store,
+  in-memory, file-based)
+- You're integrating an existing memory service (Letta, Mem0, etc.)
+
+## See also
+
+- [`CHANGELOG.md`](CHANGELOG.md) — contract revisions and fixup waves
+- RFC #2728 — design rationale
+- [`cmd/memory-plugin-postgres/`](../../workspace-server/cmd/memory-plugin-postgres/) — reference implementation
+- [`docs/api-protocol/memory-plugin-v1.yaml`](../api-protocol/memory-plugin-v1.yaml) — full OpenAPI spec
@@ -0,0 +1,124 @@
+# Pinecone-backed Memory Plugin (worked example)
+
+A working sketch of a memory plugin that delegates storage to
+[Pinecone](https://www.pinecone.io/) instead of postgres.
+
+This is **example code, not a production binary**. It demonstrates
+how to map the v1 contract onto a vector database. Operators who
+want to ship this would harden auth, add retries, batch the
+commit path, etc.
+
+## Why Pinecone is interesting
+
+The default postgres plugin's pgvector index works for ~10M memories
+on a single node. Beyond that, semantic search becomes painful. A
+managed vector database can handle 1B+ memories, but the trade-offs
+are different:
+
+- **Capabilities**: Pinecone is great at `embedding` (its core
+  feature) but has no first-class FTS. So the plugin reports
+  `["embedding"]` and ignores the `query` field.
+- **TTL**: Pinecone supports per-vector metadata with deletion via
+  metadata filter — TTL becomes a periodic janitor task, not a
+  per-row property.
+- **Cost**: per-vector billing, so the plugin should batch writes
+  and dedup before posting.
+
+## Wire mapping
+
+| Contract field | Pinecone shape |
+|---|---|
+| `namespace` | `namespace` (Pinecone's first-class concept) |
+| `id` (caller-supplied) | `id` (Pinecone vector id; plugin upserts on this) |
+| `id` (omitted) | Plugin generates `uuid.NewString()` before upsert |
+| `content` | metadata.text |
+| `embedding` | `values` |
+| `kind` / `source` / `pin` / `expires_at` | `metadata.{kind, source, pin, expires_at}` |
+| `propagation` (opaque JSON) | `metadata.propagation` (also opaque) |
+
+The contract's `expires_at` becomes a metadata field; a separate
+janitor cron periodically queries `expires_at < now` and deletes.
+
+Pinecone's native upsert is the right fit for the idempotency-key
+contract: passing the same `id` twice updates in place. So a
+Pinecone plugin gets idempotent backfill retries "for free" if it
+just forwards `MemoryWrite.id` (or its generated UUID) to the
+upsert call.
+
+## Skeleton
+
+```go
+package main
+
+import (
+    "context"
+    "encoding/json"
+    "log"
+    "net/http"
+    "os"
+
+    "github.com/pinecone-io/go-pinecone/pinecone"
+)
+
+type pineconePlugin struct {
+    client *pinecone.Client
+    index  string
+}
+
+func main() {
+    apiKey := os.Getenv("PINECONE_API_KEY")
+    if apiKey == "" {
+        log.Fatal("PINECONE_API_KEY required")
+    }
+    client, err := pinecone.NewClient(pinecone.NewClientParams{ApiKey: apiKey})
+    if err != nil {
+        log.Fatal(err)
+    }
+    p := &pineconePlugin{client: client, index: os.Getenv("PINECONE_INDEX")}
+
+    http.HandleFunc("/v1/health", p.health)
+    http.HandleFunc("/v1/search", p.search)
+    // ... rest of the routes ...
+
+    log.Fatal(http.ListenAndServe(":9100", nil))
+}
+
+func (p *pineconePlugin) health(w http.ResponseWriter, r *http.Request) {
+    w.Header().Set("Content-Type", "application/json")
+    json.NewEncoder(w).Encode(map[string]interface{}{
+        "status":       "ok",
+        "version":      "1.0.0",
+        "capabilities": []string{"embedding"}, // no FTS, no TTL out-of-box
+    })
+}
+
+func (p *pineconePlugin) search(w http.ResponseWriter, r *http.Request) {
+    // Parse contract.SearchRequest
+    // Build Pinecone QueryByVectorValuesRequest with body.Embedding
+    // For each Pinecone namespace in body.Namespaces, call Query
+    // Map results to contract.Memory
+    // ...
+}
+```
+
+## What's missing from this sketch
+
+A production-ready Pinecone plugin would add:
+
+- **Batch commits**: bulk upsert N memories in a single Pinecone call
+- **TTL janitor**: periodic deletion of expired vectors
+- **Connection pooling**: keep one Pinecone client alive across requests
+- **Retry + circuit breaker**: Pinecone occasionally returns 5xx
+- **Metrics**: latency histograms per endpoint, write/read counters
+- **Idempotency-key handling**: when `MemoryWrite.id` is supplied,
+  forward it as the Pinecone vector id verbatim; otherwise generate
+  one. Pinecone's `Upsert` is naturally idempotent on id match.
+
+But the mapping above is the load-bearing part — the rest is
+operational hardening, not contract-specific.
+
+## See also
+
+- [Pinecone Go SDK docs](https://docs.pinecone.io/reference/go-sdk)
+- [Memory plugin contract spec](../../api-protocol/memory-plugin-v1.yaml)
+- [Default postgres plugin source](../../../workspace-server/cmd/memory-plugin-postgres/) — for comparison
@@ -0,0 +1,181 @@
+# Testing Your Memory Plugin
+
+Once you have a plugin implementing the v1 contract, you can validate
+it against the spec without booting workspace-server.
+
+## The contract test harness
+
+Workspace-server ships typed Go bindings + round-trip tests in
+`workspace-server/internal/memory/contract/`. The simplest way to
+gain confidence in your plugin's wire compatibility is to point those
+tests at it.
+
+A minimal contract suite:
+
+```go
+package myplugin_test
+
+import (
+    "context"
+    "testing"
+
+    mclient "github.com/Molecule-AI/molecule-monorepo/platform/internal/memory/client"
+    "github.com/Molecule-AI/molecule-monorepo/platform/internal/memory/contract"
+)
+
+func TestMyPlugin_FullRoundTrip(t *testing.T) {
+    // Start your plugin somehow (subprocess, in-process, etc.)
+    pluginURL := startMyPlugin(t)
+    cl := mclient.New(mclient.Config{BaseURL: pluginURL})
+
+    // 1. Health
+    hr, err := cl.Boot(context.Background())
+    if err != nil {
+        t.Fatalf("Boot: %v", err)
+    }
+    if hr.Status != "ok" {
+        t.Errorf("status = %q", hr.Status)
+    }
+
+    // 2. Namespace upsert
+    if _, err := cl.UpsertNamespace(context.Background(), "workspace:test-1",
+        contract.NamespaceUpsert{Kind: contract.NamespaceKindWorkspace}); err != nil {
+        t.Fatalf("UpsertNamespace: %v", err)
+    }
+
+    // 3. Commit memory
+    resp, err := cl.CommitMemory(context.Background(), "workspace:test-1",
+        contract.MemoryWrite{
+            Content: "hello",
+            Kind:    contract.MemoryKindFact,
+            Source:  contract.MemorySourceAgent,
+        })
+    if err != nil {
+        t.Fatalf("CommitMemory: %v", err)
+    }
+    if resp.ID == "" {
+        t.Errorf("plugin must return a non-empty memory id")
+    }
+
+    // 4. Search
+    sresp, err := cl.Search(context.Background(), contract.SearchRequest{
+        Namespaces: []string{"workspace:test-1"},
+        Query:      "hello",
+    })
+    if err != nil {
+        t.Fatalf("Search: %v", err)
+    }
+    if len(sresp.Memories) == 0 {
+        t.Errorf("plugin returned no memories for the query we just wrote")
+    }
+
+    // 5. Forget
+    if err := cl.ForgetMemory(context.Background(), resp.ID,
+        contract.ForgetRequest{RequestedByNamespace: "workspace:test-1"}); err != nil {
+        t.Errorf("ForgetMemory: %v", err)
+    }
+}
+```
+
+## Testing idempotency
+
+The contract requires that `MemoryWrite.id`, when supplied, behaves
+as an upsert key. The backfill CLI relies on this — without it,
+operator retries silently duplicate every memory.
+
+```go
+func TestMyPlugin_IDIsIdempotencyKey(t *testing.T) {
+    pluginURL := startMyPlugin(t)
+    cl := mclient.New(mclient.Config{BaseURL: pluginURL})
+    if _, err := cl.UpsertNamespace(context.Background(), "workspace:test-1",
+        contract.NamespaceUpsert{Kind: contract.NamespaceKindWorkspace}); err != nil {
+        t.Fatal(err)
+    }
+
+    fixedID := "11111111-2222-3333-4444-555555555555"
+
+    // First write with a specific id.
+    resp1, err := cl.CommitMemory(context.Background(), "workspace:test-1",
+        contract.MemoryWrite{
+            ID:      fixedID,
+            Content: "first version",
+            Kind:    contract.MemoryKindFact,
+            Source:  contract.MemorySourceAgent,
+        })
+    if err != nil {
+        t.Fatalf("first commit: %v", err)
+    }
+    if resp1.ID != fixedID {
+        t.Errorf("plugin must echo the supplied id, got %q", resp1.ID)
+    }
+
+    // Second write with the same id — must update, not insert.
+    if _, err := cl.CommitMemory(context.Background(), "workspace:test-1",
+        contract.MemoryWrite{
+            ID:      fixedID,
+            Content: "second version (updated)",
+            Kind:    contract.MemoryKindFact,
+            Source:  contract.MemorySourceAgent,
+        }); err != nil {
+        t.Fatalf("second commit: %v", err)
+    }
+
+    // Search must return exactly one row, with the updated content.
+    sresp, _ := cl.Search(context.Background(), contract.SearchRequest{
+        Namespaces: []string{"workspace:test-1"},
+    })
+    matches := 0
+    for _, m := range sresp.Memories {
+        if m.ID == fixedID {
+            matches++
+            if m.Content != "second version (updated)" {
+                t.Errorf("upsert didn't update content: got %q", m.Content)
+            }
+        }
+    }
+    if matches != 1 {
+        t.Errorf("upsert produced %d rows for id=%s, want 1", matches, fixedID)
+    }
+}
+```
+
+## What the harness does NOT cover
+
+- **Capability accuracy**: if you list `embedding` you must actually
+  do semantic search. The harness can't tell you whether ranking is
+  meaningful — only that you don't crash.
+- **TTL eviction**: write a memory with `expires_at` 1 second in the
+  future, sleep 2 seconds, search — assert the memory is gone.
+- **Concurrency**: hit your plugin with 100 parallel writes; assert
+  no IDs collide.
+- **Recovery**: kill your plugin's storage backend, send a request,
+  assert your plugin returns 503 (not 200 with stale data).
+- **Backfill compatibility**: run the operator backfill against your
+  plugin twice in a row (`memory-backfill -apply`); assert the row
+  count doesn't double. The idempotency test above verifies the unit
+  contract; this checks the operational integration.
+- **Verify-mode parity**: after a backfill, run `memory-backfill
+  -verify`; assert it reports zero mismatches against
+  `agent_memories`.
+
+## Smoke test against workspace-server
+
+Once unit-level wire tests pass, run a real workspace-server with your
+plugin URL:
+
+```bash
+DATABASE_URL=postgres://... \
+MEMORY_PLUGIN_URL=http://localhost:9100 \
+./workspace-server
+```
+
+Then ask an agent to call `commit_memory_v2` and `search_memory`. If
+both round-trip cleanly, you're done.
+
+For the full E2E flow (including the namespace resolver, MCP layer,
+and security perimeter), see [PR-11's plugin-swap test](../../workspace-server/test/e2e/memory_plugin_swap_test.go).
+
+## Reporting bugs
+
+If you find a contract ambiguity or missing edge case, file an issue
+against `Molecule-AI/molecule-core` referencing RFC #2728.
@@ -1,5 +1,14 @@
 # Workspace Runtime PyPI Package

+## Requires Python >= 3.11
+
+The wheel pins `requires_python>=3.11`. On Python 3.10 or older, `pip install
+molecule-ai-workspace-runtime` fails with `Could not find a version that
+satisfies the requirement (from versions: none)` — the pin filters the only
+available artifact before pip even attempts install. Upgrade the interpreter
+(`brew install python@3.12` / `apt install python3.12` / etc.) or use a
+3.11+ venv.
+
 ## Overview

 The shared workspace runtime infrastructure has **one editable source** and
@@ -55,9 +55,15 @@ TOP_LEVEL_MODULES = {
    "a2a_executor",
    "a2a_mcp_server",
    "a2a_tools",
+    "a2a_tools_delegation",
+    "a2a_tools_memory",
+    "a2a_tools_messaging",
+    "a2a_tools_rbac",
    "adapter_base",
    "agent",
    "agents_md",
+    "boot_routes",
+    "card_helpers",
    "config",
    "configs_dir",
    "consolidation",
@@ -67,18 +73,24 @@ TOP_LEVEL_MODULES = {
    "executor_helpers",
    "heartbeat",
    "inbox",
+    "inbox_uploads",
    "initial_prompt",
    "internal_chat_uploads",
    "internal_file_read",
    "main",
    "mcp_cli",
+    "mcp_heartbeat",
+    "mcp_inbox_pollers",
+    "mcp_workspace_resolver",
    "molecule_ai_status",
+    "not_configured_handler",
    "platform_auth",
    "platform_inbound_auth",
    "plugins",
    "preflight",
    "prompt",
    "runtime_wedge",
+    "secret_redactor",
    "shared_runtime",
    "smoke_mode",
    "transcript_auth",
@@ -278,10 +290,37 @@ directory** by the `publish-runtime` GitHub Actions workflow on every
 Operators running an agent outside the platform's container fleet
 (any runtime that supports MCP stdio — Claude Code, hermes, codex,
 etc.) can install this wheel and run the universal MCP server
-locally:
+locally.
+
+### Requirements
+
+* **Python ≥3.11.** The wheel sets `requires-python = ">=3.11"`. On
+  older interpreters `pip install` returns the cryptic
+  `Could not find a version that satisfies the requirement` — that
+  message is pip filtering this wheel out, NOT the package missing
+  from PyPI. Upgrade with `brew install python@3.12` /
+  `apt install python3.12` / `pyenv install 3.12` first.
+* **`pipx` recommended over `pip`.** `pipx install` puts
+  `molecule-mcp` on PATH automatically and isolates the runtime's
+  deps from your system Python. Plain `pip install --user` works
+  but the binary lands in `~/.local/bin` (Linux) or
+  `~/Library/Python/3.X/bin` (macOS) which is often not on PATH on
+  a fresh shell — `claude mcp add molecule -- molecule-mcp` then
+  fails with "command not found" at first use.
+
+### Install
+
+```sh
+# Recommended:
+pipx install molecule-ai-workspace-runtime
+
+# Alternative (manage PATH yourself):
+pip install --user molecule-ai-workspace-runtime
+```
+
+### Run

 ```sh
-pip install molecule-ai-workspace-runtime
 WORKSPACE_ID=<uuid> \\
  PLATFORM_URL=https://<tenant>.staging.moleculesai.app \\
  MOLECULE_WORKSPACE_TOKEN=<bearer> \\
@@ -294,10 +333,64 @@ runtimes already get via the workspace's auto-spawned MCP. Register
 the binary in your agent's MCP config (e.g. Claude Code's
 `claude mcp add molecule -- molecule-mcp` with the env above).

+### Keeping the token out of shell history
+
+Inline `MOLECULE_WORKSPACE_TOKEN=<bearer>` ends up in `~/.zsh_history`
+and (when registered via `claude mcp add`) plaintext in
+`~/.claude.json`. To avoid that, write the token to a 0600 file and
+point `MOLECULE_WORKSPACE_TOKEN_FILE` at it:
+
+```sh
+umask 077
+printf '%s' "<bearer>" > ~/.config/molecule/token
+WORKSPACE_ID=<uuid> \\
+  PLATFORM_URL=https://<tenant>.staging.moleculesai.app \\
+  MOLECULE_WORKSPACE_TOKEN_FILE=$HOME/.config/molecule/token \\
+  molecule-mcp
+```
+
+Token resolution order: `MOLECULE_WORKSPACE_TOKEN` (inline env) →
+`MOLECULE_WORKSPACE_TOKEN_FILE` (path) → `${CONFIGS_DIR}/.auth_token`
+(in-container default).
+
 The token comes from the canvas → Tokens tab. Restarting an external
 workspace from the canvas no longer revokes the token (PR #2412), so
 operator tokens persist across status nudges.

+### Push vs poll delivery (Claude Code specifics)
+
+By default the inbox runs in **poll mode** — every turn the agent
+calls `wait_for_message`, which blocks up to ~60s on
+`/activity?since_id=…`. Real-time push delivery is also supported,
+but on Claude Code it requires THREE conditions, ALL of which must
+hold:
+
+1. **The MCP server declares `experimental.claude/channel`** — this
+   wheel does (see `_build_initialize_result`). Nothing for you to
+   do.
+2. **Claude Code installs the server as a marketplace plugin** — a
+   plain `claude mcp add molecule -- molecule-mcp` produces a
+   non-plugin-sourced server, which Claude Code rejects with
+   `channel_enable requires a marketplace plugin`. Until the
+   official `moleculesai/claude-code-plugin` marketplace lands
+   (issue #2934 follow-up), operators who want push must scaffold
+   their own local marketplace under
+   `~/.claude/marketplaces/molecule-local/` containing a
+   `marketplace.json` + `plugin.json` that points at this wheel.
+3. **Claude Code is launched with the dev-channels flag** — pass
+   `--dangerously-load-development-channels plugin:molecule@<marketplace>`
+   on the `claude` invocation. Without this flag the channel
+   capability is silently ignored.
+
+Symptom of any condition failing: messages arrive but only via the
+poll path (every ~1–60s), not real-time. There's currently no
+diagnostic surfaced — `molecule-mcp doctor` (issue #2934 follow-up)
+is planned.
+
+If you don't need real-time push, the default poll path works
+universally with no extra setup; both modes converge on the same
+`inbox_pop` ack so messages never duplicate.
+
 See [`docs/workspace-runtime-package.md`](https://github.com/Molecule-AI/molecule-core/blob/main/docs/workspace-runtime-package.md)
 for the publish flow and architecture.
 """
@@ -0,0 +1,51 @@
+#!/usr/bin/env bash
+# Per-runtime model slug dispatch for E2E provisioning.
+#
+# Different runtimes parse the model slug differently (PR #2571 incident,
+# 2026-05-03):
+#
+#   hermes      → "openai/gpt-4o"  (slash-form: derive-provider.sh splits
+#                                    on the prefix to set
+#                                    HERMES_INFERENCE_PROVIDER. Bare
+#                                    "gpt-4o" falls through to Anthropic
+#                                    default + 401, see PR #1714.)
+#
+#   langgraph   → "openai:gpt-4o"  (colon-form: langchain init_chat_model
+#                                    requires "<provider>:<model>".
+#                                    Slash-form was misinterpreted as
+#                                    OpenRouter routing → fell through
+#                                    without auth, surfaced 2026-05-03
+#                                    after the a2a-sdk v1 contract bugs
+#                                    PR #2558+#2563+#2567 cleared the
+#                                    masking layers.)
+#
+#   claude-code → "sonnet"         (entry-id form: claude-code template's
+#                                    config.yaml uses bare model names,
+#                                    auth comes via CLAUDE_CODE_OAUTH_TOKEN
+#                                    or ANTHROPIC_API_KEY rather than the
+#                                    slug.)
+#
+# When E2E_MODEL_SLUG is set, it overrides this dispatch — useful when an
+# operator dispatches the workflow to test a specific slug.
+#
+# Unit tested by tests/e2e/test_model_slug.sh — every branch must stay
+# pinned because regressions silently mask as "Could not resolve
+# authentication method" + the synth-E2E gate goes red without naming
+# the slug-format mismatch.
+
+# Usage: pick_model_slug <runtime>
+#   stdout: the slug string
+#   E2E_MODEL_SLUG (env): if set + non-empty, used as-is (operator override)
+pick_model_slug() {
+  local runtime="${1:-}"
+  if [ -n "${E2E_MODEL_SLUG:-}" ]; then
+    printf '%s' "$E2E_MODEL_SLUG"
+    return 0
+  fi
+  case "$runtime" in
+    hermes)      printf 'openai/gpt-4o' ;;
+    langgraph)   printf 'openai:gpt-4o' ;;
+    claude-code) printf 'sonnet' ;;
+    *)           printf 'openai/gpt-4o' ;;  # safest fallback (matches hermes)
+  esac
+}
@@ -0,0 +1,40 @@
+#!/usr/bin/env bash
+# lint_cleanup_traps.sh — regression gate for the OSS-shape program's
+# "all E2E tests must have proper cleanup" bar (RFC #2873).
+#
+# Asserts: every shell file under tests/e2e/ that calls `mktemp` ALSO
+# installs an `EXIT` trap somewhere in the file. The trap is the
+# minimum-viable guarantee that scratch files won't leak when an
+# assertion or curl exits the script non-zero.
+#
+# Why this lints (instead of the test runner enforcing): shell scripts
+# can't easily be wrapped by an outer harness without breaking the
+# `WSID=… ./test_x.sh` invocation contract. Static gate is the cheap
+# defense.
+#
+# Usage:
+#   tests/e2e/lint_cleanup_traps.sh
+#
+# Exits non-zero if any test_*.sh has unmatched mktemp/trap. CI invokes
+# it from the existing Shellcheck (E2E scripts) workflow.
+
+set -euo pipefail
+
+cd "$(dirname "$0")"
+
+violations=0
+for f in test_*.sh; do
+  if grep -qE '\bmktemp\b' "$f"; then
+    if ! grep -qE 'trap[[:space:]]+.*EXIT' "$f"; then
+      echo "::error file=tests/e2e/$f::has 'mktemp' but no 'trap … EXIT' — scratch will leak when test exits non-zero. Pattern: TMPDIR_E2E=\$(mktemp -d -t prefix-XXX); trap 'rm -rf \"\$TMPDIR_E2E\"' EXIT INT TERM"
+      violations=$((violations + 1))
+    fi
+  fi
+done
+
+if [ "$violations" -gt 0 ]; then
+  echo "::error::$violations shell E2E file(s) leak scratch on early exit. See above."
+  exit 1
+fi
+
+echo "✓ all $(grep -lE '\bmktemp\b' test_*.sh | wc -l | tr -d ' ') shell E2E files with mktemp also install an EXIT trap"
--- a/Show More
+++ b/Show More