fix(canvas/test): add missing FilesToolbar import + renderToolbar helper

PR #881 rewrote FilesTab.test.tsx and deleted renderToolbar(), but left one orphaned test inside the "upload guard" block that called it. Adds the import + helper so the focus-visible accessibility test runs. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Merge pull request 'fix(ci): /sop-n/a slash command to skip RFC#324 gates for N/A PRs' (#915 ) from fix/rfc324-na-gate into main
2026-05-14 01:25:11 +00:00 · 2026-05-14 01:14:25 +00:00 · 2026-05-14 01:04:11 +00:00 · 2026-05-14 00:44:40 +00:00 · 2026-05-14 00:43:29 +00:00 · 2026-05-14 00:43:29 +00:00
29 changed files with 2096 additions and 297 deletions
@@ -101,9 +101,10 @@ printf 'header = "Authorization: token %s"\n' "$GITEA_TOKEN" > "$CURL_AUTH_FILE"
 PR_JSON=$(mktemp)
 REVIEWS_JSON=$(mktemp)
 TEAM_PROBE_TMP=$(mktemp)
+NA_STATUSES_TMP=""  # declared here so cleanup() always has the var

 cleanup() {
-  rm -f "$CURL_AUTH_FILE" "$PR_JSON" "$REVIEWS_JSON" "$TEAM_PROBE_TMP"
+  rm -f "$CURL_AUTH_FILE" "$PR_JSON" "$REVIEWS_JSON" "$TEAM_PROBE_TMP" "${NA_STATUSES_TMP-}"
 }
 trap cleanup EXIT

@@ -143,6 +144,42 @@ if [ -z "$PR_AUTHOR" ] || [ -z "$PR_HEAD_SHA" ]; then
  exit 1
 fi

+# --- RFC#324 §N/A follow-up: check N/A declarations status ---
+# sop-checklist-gate.py posts `sop-checklist / na-declarations (pull_request)`
+# status when a peer posts /sop-n/a <gate>. If our gate is declared N/A,
+# the requirement for a Gitea APPROVE review is waived.
+NA_STATUSES_TMP=$(mktemp)
+HTTP_CODE=$(curl -sS -o "$NA_STATUSES_TMP" -w '%{http_code}' \
+  -K "$CURL_AUTH_FILE" "${API}/repos/${OWNER}/${NAME}/statuses/${PR_HEAD_SHA}")
+debug "statuses/${PR_HEAD_SHA} → HTTP ${HTTP_CODE}"
+
+if [ "$HTTP_CODE" = "200" ]; then
+  # Gitea returns statuses as array; look for the na-declarations context.
+  # jq: find all statuses where context == "sop-checklist / na-declarations (pull_request)"
+  # and state == "success". Extract the description field.
+  NA_DESC=$(jq -r '
+    .[] |
+    select(.context == "sop-checklist / na-declarations (pull_request)") |
+    select(.state == "success") |
+    .description
+  ' "$NA_STATUSES_TMP" 2>/dev/null | head -1)
+
+  if [ -n "$NA_DESC" ] && [ "$NA_DESC" != "null" ]; then
+    debug "na-declarations status found: ${NA_DESC}"
+    # Check if our gate appears in the N/A description.
+    # The description format is "N/A: qa-review, security-review" or similar.
+    if echo "$NA_DESC" | grep -iq "\\b${TEAM}-review\\b"; then
+      echo "::notice::${TEAM}-review N/A — gate declared not-applicable via /sop-n/a: ${NA_DESC}"
+      echo "::notice::PR ${PR_NUMBER} passes ${TEAM}-review via N/A declaration"
+      rm -f "$NA_STATUSES_TMP"
+      exit 0
+    fi
+  fi
+else
+  debug "could not fetch statuses (HTTP ${HTTP_CODE}) — proceeding with normal eval"
+fi
+rm -f "$NA_STATUSES_TMP"
+
 # --- Fetch all reviews on the PR ---
 HTTP_CODE=$(curl -sS -o "$REVIEWS_JSON" -w '%{http_code}' \
  -K "$CURL_AUTH_FILE" "${API}/repos/${OWNER}/${NAME}/pulls/${PR_NUMBER}/reviews")
@@ -109,57 +109,58 @@ def normalize_slug(raw: str, numeric_aliases: dict[int, str] | None = None) -> s
 # Optional trailing note after the slug for /sop-ack and required reason
 # for /sop-revoke (RFC#351 open question 4 — reason is captured but not
 # yet validated; future iteration may require a min-length).
+#
+# /sop-n/a <gate> [reason] — declares a gate as not-applicable.
+#   <gate> is a canonical gate name (qa-review, security-review).
+#   The declaring user must be in one of the gate's required_teams.
+#   Most-recent per-user declaration wins (revoke semantics mirror ack).
 _DIRECTIVE_RE = re.compile(
    r"^[ \t]*/(sop-ack|sop-revoke)[ \t]+([A-Za-z0-9_\- ]+?)(?:[ \t]+(.*))?[ \t]*$",
    re.MULTILINE,
 )
+_NA_DIRECTIVE_RE = re.compile(
+    r"^[ \t]*/sop-n/?a[ \t]+([A-Za-z0-9_\-]+)(?:[ \t]+(.*))?[ \t]*$",
+    re.MULTILINE,
+)


 def parse_directives(
    comment_body: str,
    numeric_aliases: dict[int, str],
-) -> list[tuple[str, str, str]]:
-    """Extract /sop-ack and /sop-revoke directives from a comment body.
+) -> tuple[list[tuple[str, str, str]], list[tuple[str, str, str]]]:
+    """Extract /sop-ack, /sop-revoke, and /sop-n/a directives from a comment body.

-    Returns a list of (kind, canonical_slug, note) tuples where:
-      kind is "sop-ack" or "sop-revoke"
-      canonical_slug is the normalized form (or "" if unparseable)
-      note is the trailing free-text (may be "")
+    Returns a tuple of two lists:
+      0. list of (kind, canonical_slug, note) for sop-ack/sop-revoke
+      1. list of (kind, gate_name, reason) for sop-n/a
+
+    canonical_slug is the normalized form (or "" if unparseable).
+    note/reason is the trailing free-text (may be "").
    """
    out: list[tuple[str, str, str]] = []
+    na_out: list[tuple[str, str, str]] = []
    if not comment_body:
-        return out
+        return out, na_out
    for m in _DIRECTIVE_RE.finditer(comment_body):
        kind = m.group(1)
        raw_slug = (m.group(2) or "").strip()
-        # If the raw match included trailing words, the regex non-greedy
-        # captured only the first token; strip again for safety.
-        # We split on whitespace to keep the FIRST word as the slug, and
-        # everything after as the note.
        parts = raw_slug.split()
        if not parts:
            continue
        first = parts[0]
-        # If the slug-capture greedily matched multiple words (e.g.
-        # "comprehensive testing"), preserve normalize behavior: join
-        # the WHOLE first-word-token only; trailing words get appended to
-        # the note. The regex limits group(2) to [A-Za-z0-9_\- ] so we
-        # may have multi-word forms here — normalize handles them.
        if len(parts) > 1:
-            # User wrote "/sop-ack comprehensive testing extra-note"
-            # → treat "comprehensive testing" as the slug source if it
-            # normalizes to a known item; otherwise treat "comprehensive"
-            # as slug and "testing extra-note" as note. We defer the
-            # disambiguation to the caller via the returned canonical
-            # slug. For simplicity: try the WHOLE captured string first.
            canonical = normalize_slug(raw_slug, numeric_aliases)
        else:
            canonical = normalize_slug(first, numeric_aliases)
        note_from_group = (m.group(3) or "").strip()
-        # If we collapsed multi-word slug into kebab and there's a
-        # trailing-text group too, append it.
        out.append((kind, canonical, note_from_group))
-    return out
+
+    for m in _NA_DIRECTIVE_RE.finditer(comment_body):
+        gate = (m.group(1) or "").strip().lower()
+        reason = (m.group(2) or "").strip()
+        na_out.append(("sop-n/a", gate, reason))
+
+    return out, na_out


 # ---------------------------------------------------------------------------
@@ -230,9 +231,8 @@ def compute_ack_state(
       {
         "comprehensive-testing": {
           "ackers": ["bob"],         # non-author, team-verified
-           "rejected_ackers": {        # debugging info
+           "rejected": {
             "self_ack": ["alice"],
-             "unknown_slug": [],
             "not_in_team": ["eve"],
           }
         },
@@ -249,7 +249,8 @@ def compute_ack_state(
        user = (c.get("user") or {}).get("login", "")
        if not user:
            continue
-        for kind, slug, _note in parse_directives(body, numeric_aliases):
+        directives, _na_directives = parse_directives(body, numeric_aliases)
+        for kind, slug, _note in directives:
            if not slug:
                unparseable_per_user[user] = unparseable_per_user.get(user, 0) + 1
                continue
@@ -259,25 +260,19 @@ def compute_ack_state(
    # Filter out self-acks and unknown slugs.
    ackers_per_slug: dict[str, list[str]] = {s: [] for s in items_by_slug}
    rejected_self: dict[str, list[str]] = {s: [] for s in items_by_slug}
-    rejected_unknown: dict[str, list[str]] = {s: [] for s in items_by_slug}
    pending_team_check: dict[str, list[str]] = {s: [] for s in items_by_slug}

    for (user, slug), kind in latest_directive.items():
        if kind != "sop-ack":
            continue  # revokes leave the (user,slug) state as "no ack"
        if slug not in items_by_slug:
-            # Slug normalized to something not in our config — store
-            # under a synthetic key for diagnostic surfacing. Don't add
-            # to any item.
            continue
        if user == pr_author:
            rejected_self[slug].append(user)
            continue
        pending_team_check[slug].append(user)

-    # Step 3: team membership probe per slug (batched per slug to keep
-    # API call count down — same user may ack multiple items but the
-    # required_teams differ per item, so we MUST probe per (user, item)).
+    # Step 3: team membership probe per slug.
    rejected_not_in_team: dict[str, list[str]] = {s: [] for s in items_by_slug}
    for slug, candidates in pending_team_check.items():
        if not candidates:
@@ -286,7 +281,6 @@ def compute_ack_state(
        approved = team_membership_probe(slug, candidates)  # returns subset
        rejected_not_in_team[slug] = [u for u in candidates if u not in approved]
        ackers_per_slug[slug] = approved
-        # Stash required teams for description rendering.
        items_by_slug[slug]["_required_resolved"] = required

    return {
@@ -301,6 +295,113 @@ def compute_ack_state(
    }


+def compute_na_state(
+    comments: list[dict[str, Any]],
+    pr_author: str,
+    na_gates: dict[str, dict[str, Any]],
+    numeric_aliases: dict[int, str],
+    team_membership_probe: "callable[[str, list[str]], list[str]]",
+    client: "GiteaClient",
+    org: str,
+) -> dict[str, dict[str, Any]]:
+    """Compute per-gate N/A declaration state.
+
+    Returns a dict keyed by gate name:
+       {
+         "qa-review": {
+           "declared":  ["alice"],      # non-author, team-verified, not revoked
+           "rejected": ["eve (not-in-team)", "bob (self-decl)"],
+           "reason":   "pure-infra change — no qa surface",
+         },
+         ...
+       }
+    A gate is N/A-satisfied when at least one declaration from a valid
+    team member exists and has not been revoked by the same user.
+    """
+    if not na_gates:
+        return {}
+
+    # Collapse directives per (commenter, gate) — most recent wins.
+    latest_na: dict[tuple[str, str], str] = {}   # (user, gate) → "sop-n/a"
+    latest_na_reason: dict[tuple[str, str], str] = {}  # (user, gate) → reason
+    for c in comments:
+        body = c.get("body", "") or ""
+        user = (c.get("user") or {}).get("login", "")
+        if not user:
+            continue
+        _directives, na_directives = parse_directives(body, numeric_aliases)
+        for _kind, gate, reason in na_directives:
+            if gate not in na_gates:
+                continue
+            latest_na[(user, gate)] = "sop-n/a"
+            latest_na_reason[(user, gate)] = reason
+
+    # Determine candidate declarers per gate.
+    na_state: dict[str, dict[str, Any]] = {
+        gate: {"declared": [], "rejected": [], "reason": ""}
+        for gate in na_gates
+    }
+    pending_per_gate: dict[str, list[str]] = {gate: [] for gate in na_gates}
+
+    for (user, gate), kind in latest_na.items():
+        if kind != "sop-n/a":
+            continue
+        if user == pr_author:
+            na_state[gate]["rejected"].append(f"{user} (self-decl)")
+            continue
+        pending_per_gate[gate].append(user)
+
+    # Probe team membership per gate using that gate's required_teams.
+    for gate, candidates in pending_per_gate.items():
+        if not candidates:
+            continue
+        required_teams = na_gates[gate].get("required_teams", [])
+        # Resolve team names → ids using the client's resolver.
+        team_ids: list[int] = []
+        for tn in required_teams:
+            tid = client.resolve_team_id(org, tn)
+            if tid is not None:
+                team_ids.append(tid)
+        if not team_ids:
+            na_state[gate]["rejected"].extend(
+                f"{u} (no-team-id)" for u in candidates
+            )
+            continue
+        for u in candidates:
+            in_any_team = False
+            for tid in team_ids:
+                result = client.is_team_member(tid, u)
+                if result is True:
+                    in_any_team = True
+                    break
+                if result is None:
+                    # 403 — token owner not in team. Fail-closed.
+                    print(
+                        f"::warning::na: team-probe for {u} in team-id {tid} "
+                        "returned 403 — treating as not-in-team (fail-closed)",
+                        file=sys.stderr,
+                    )
+            if in_any_team:
+                na_state[gate]["declared"].append(u)
+            else:
+                na_state[gate]["rejected"].append(f"{u} (not-in-team)")
+
+    # Build per-gate reason string from declared users.
+    for gate in na_gates:
+        decl = na_state[gate]["declared"]
+        if decl:
+            reasons: list[str] = []
+            for u in decl:
+                r = latest_na_reason.get((u, gate), "")
+                if r:
+                    reasons.append(f"{u}: {r}")
+                else:
+                    reasons.append(u)
+            na_state[gate]["reason"] = "; ".join(reasons)
+
+    return na_state
+
+
 # ---------------------------------------------------------------------------
 # Gitea API client
 # ---------------------------------------------------------------------------
@@ -698,6 +799,7 @@ def main(argv: list[str] | None = None) -> int:
    numeric_aliases = {
        int(it["numeric_alias"]): it["slug"] for it in items if it.get("numeric_alias")
    }
+    na_gates: dict[str, dict[str, Any]] = cfg.get("n/a_gates") or {}

    client = GiteaClient(args.gitea_host, token) if token else None
    if not client:
@@ -717,6 +819,8 @@ def main(argv: list[str] | None = None) -> int:
        print("::error::PR payload missing user.login or head.sha", file=sys.stderr)
        return 1

+    target_url = f"https://{args.gitea_host}/{args.owner}/{args.repo}/pulls/{args.pr}"
+
    comments = client.get_issue_comments(args.owner, args.repo, args.pr)

    # Build team-membership probe closure that caches results per
@@ -774,6 +878,47 @@ def main(argv: list[str] | None = None) -> int:
    ack_state = compute_ack_state(comments, author, items_by_slug, numeric_aliases, probe)
    body_state = {it["slug"]: section_marker_present(body, it["pr_section_marker"]) for it in items}

+    # --- N/A gate state (RFC#324 §N/A follow-up) ---
+    na_state: dict[str, dict[str, Any]] = {}
+    if na_gates:
+        na_state = compute_na_state(
+            comments, author, na_gates, numeric_aliases,
+            probe, client, args.owner,
+        )
+        # Post N/A declarations status (read by review-check.sh).
+        na_satisfied = [g for g, s in na_state.items() if s["declared"]]
+        na_missing   = [g for g, s in na_state.items() if not s["declared"]]
+        if na_satisfied:
+            na_desc = f"N/A: {', '.join(na_satisfied)}"
+            na_post_state = "success"
+        elif na_missing:
+            na_desc = f"awaiting /sop-n/a declaration for: {', '.join(na_missing)}"
+            na_post_state = "pending"
+        else:
+            # Configured but no declarations yet.
+            na_desc = "no /sop-n/a declarations yet"
+            na_post_state = "pending"
+        na_context = "sop-checklist / na-declarations (pull_request)"
+        print(f"::notice::na-declarations status: {na_post_state} — {na_desc}")
+        if not args.dry_run:
+            client.post_status(
+                args.owner, args.repo, head_sha,
+                state=na_post_state, context=na_context,
+                description=na_desc,
+                target_url=target_url,
+            )
+            print(f"::notice::na-declarations status posted: {na_context} → {na_post_state}")
+        # Log per-gate diagnostics.
+        for gate in na_gates:
+            s = na_state.get(gate, {})
+            if s.get("declared"):
+                print(f"::notice::  [PASS] gate={gate} — N/A declared by {','.join(s['declared'])}"
+                      + (f" ({s['reason']})" if s.get("reason") else ""))
+            else:
+                extra = f" — rejected: {', '.join(s.get('rejected', []))}" if s.get("rejected") else ""
+                print(f"::notice::  [WAIT] gate={gate} — no valid N/A declaration yet{extra}")
+
+
    state, description = render_status(items, ack_state, body_state)
    mode = get_tier_mode(pr, cfg)
    if mode == "soft":
@@ -808,7 +953,6 @@ def main(argv: list[str] | None = None) -> int:
            return 0 if state in ("success", "pending") else 1
        return 0

-    target_url = f"https://{args.gitea_host}/{args.owner}/{args.repo}/pulls/{args.pr}"
    client.post_status(
        args.owner, args.repo, head_sha,
        state=state, context=args.status_context,
@@ -107,3 +107,39 @@ items:
    description: >-
      List of feedback memories applicable to this change. Ack from
      any engineer who has the same memory access.
+
+# N/A gate declarations (RFC#324 §N/A follow-up).
+# PRs where a gate genuinely does not apply (e.g., pure-infra with no
+# qa surface, or docs-only) can be declared N/A by a non-author peer
+# who is in one of the gate's required_teams. The sop-checklist-gate
+# posts a `sop-checklist / na-declarations (pull_request)` status that
+# review-check.sh reads to skip the Gitea-APPROVE requirement.
+#
+# Usage: any PR commenter (peer) posts:
+#   /sop-n/a qa-review  <reason>
+#   /sop-n/a security-review  <reason>
+#
+# Slash commands:
+#   /sop-n/a <gate> [reason] — declare gate N/A (most-recent per-user wins)
+#   /sop-revoke <gate>      — revoke prior N/A declaration for that gate
+#
+# Gate names must match the context strings used by review-check.sh:
+#   qa-review      → qa-review / approved (<event>)        [TEAM_ID=20]
+#   security-review → security-review / approved (<event>)  [TEAM_ID=21]
+#
+# required_teams: OR semantics — any team member can declare N/A.
+# Authors cannot self-declare N/A (enforced by gate script).
+n/a_gates:
+  qa-review:
+    required_teams: [qa, security, engineers]
+    description: >-
+      QA review N/A when this change has no qa surface (pure-infra,
+      tooling-only, revert, dependency-only). A qa/eng/security member
+      must post /sop-n/a qa-review to activate.
+
+  security-review:
+    required_teams: [security, managers, ceo]
+    description: >-
+      Security review N/A when this change has no security surface
+      (docs-only, pure-frontend, dependency-only). A security/owners
+      member must post /sop-n/a security-review to activate.
@@ -107,16 +107,25 @@ jobs:
            echo "scripts=true" >> "$GITHUB_OUTPUT"
            exit 0
          fi
-          # Both .github/workflows/ci.yml AND .gitea/workflows/ci.yml count
-          # as "this workflow changed" — either edit should force-run every
-          # downstream job. The Gitea port follows the same shape as the
-          # GitHub original so behavior matches when triggered on either
-          # platform.
-          DIFF=$(git diff --name-only "$BASE" HEAD 2>/dev/null || echo ".gitea/workflows/ci.yml")
-          echo "platform=$(echo "$DIFF" | grep -qE '^workspace-server/|^\.gitea/workflows/ci\.yml$|^\.github/workflows/ci\.yml$' && echo true || echo false)" >> "$GITHUB_OUTPUT"
-          echo "canvas=$(echo "$DIFF" | grep -qE '^canvas/|^\.gitea/workflows/ci\.yml$|^\.github/workflows/ci\.yml$' && echo true || echo false)" >> "$GITHUB_OUTPUT"
-          echo "python=$(echo "$DIFF" | grep -qE '^workspace/|^\.gitea/workflows/ci\.yml$|^\.github/workflows/ci\.yml$' && echo true || echo false)" >> "$GITHUB_OUTPUT"
-          echo "scripts=$(echo "$DIFF" | grep -qE '^tests/e2e/|^scripts/|^infra/scripts/|^\.gitea/workflows/ci\.yml$|^\.github/workflows/ci\.yml$' && echo true || echo false)" >> "$GITHUB_OUTPUT"
+          # Workflow-only edits are covered by the workflow lint family
+          # and by this workflow's always-present required jobs. Do not fan
+          # those edits out into Go/Canvas/Python/shellcheck work; the
+          # downstream jobs still emit their required contexts via no-op
+          # steps when their surface flag is false.
+          #
+          # If the diff itself cannot be trusted, fail open by running every
+          # surface instead of silently under-testing the PR.
+          if ! DIFF=$(git diff --name-only "$BASE" HEAD 2>/dev/null); then
+            echo "platform=true" >> "$GITHUB_OUTPUT"
+            echo "canvas=true" >> "$GITHUB_OUTPUT"
+            echo "python=true" >> "$GITHUB_OUTPUT"
+            echo "scripts=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "platform=$(echo "$DIFF" | grep -qE '^workspace-server/' && echo true || echo false)" >> "$GITHUB_OUTPUT"
+          echo "canvas=$(echo "$DIFF" | grep -qE '^canvas/' && echo true || echo false)" >> "$GITHUB_OUTPUT"
+          echo "python=$(echo "$DIFF" | grep -qE '^workspace/' && echo true || echo false)" >> "$GITHUB_OUTPUT"
+          echo "scripts=$(echo "$DIFF" | grep -qE '^tests/e2e/|^scripts/|^infra/scripts/' && echo true || echo false)" >> "$GITHUB_OUTPUT"

  # Platform (Go) — Go build/vet/test/lint + coverage gates. The always-run
  # + per-step gating shape preserves the GitHub-side required-check name
@@ -380,17 +389,27 @@ jobs:
    # mc#774: pre-existing continue-on-error mask; root-fix and remove, do not renew silently.
    continue-on-error: true
    needs: [changes, canvas-build]
-    # Only fires on direct pushes to main (i.e. after staging→main promotion).
-    if: needs.changes.outputs.canvas == 'true' && github.event_name == 'push' && github.ref == 'refs/heads/main'
+    # Keep the job itself always runnable. Gitea 1.22.6 leaves job-level
+    # event/ref `if:` gates as pending on PRs, which blocks the combined
+    # status even though this reminder is intentionally non-required.
    steps:
      - name: Write deploy reminder to step summary
        env:
          COMMIT_SHA: ${{ github.sha }}
+          CANVAS_CHANGED: ${{ needs.changes.outputs.canvas }}
+          EVENT_NAME: ${{ github.event_name }}
+          REF_NAME: ${{ github.ref }}
          # github.server_url resolves via the workflow-level env override
          # to the Gitea instance, so the RUN_URL points at the Gitea run
          # page (not github.com). See feedback_act_runner_github_server_url.
          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
        run: |
+          set -euo pipefail
+          if [ "$CANVAS_CHANGED" != "true" ] || [ "$EVENT_NAME" != "push" ] || [ "$REF_NAME" != "refs/heads/main" ]; then
+            echo "Canvas deploy reminder not applicable for event=$EVENT_NAME ref=$REF_NAME canvas_changed=$CANVAS_CHANGED."
+            exit 0
+          fi
+
          # Write body to a temp file — avoids backtick escaping in shell.
          cat > /tmp/deploy-reminder.md << 'BODY'
          ## Canvas build passed — deploy required
@@ -535,11 +554,10 @@ jobs:
    #     hourly if this list diverges from status_check_contexts or from
    #     audit-force-merge.yml's REQUIRED_CHECKS env (RFC §4 + §6).
    #
-    # Excluded from `needs:`: `canvas-deploy-reminder` — gated by
-    # `if: ... github.event_name == 'push' && github.ref == 'refs/heads/main'`,
-    # so on PR events it's legitimately `skipped`. The drift detector
-    # explicitly excludes `github.event_name`-gated jobs from F1 (see
-    # `.gitea/scripts/ci-required-drift.py::ci_job_names`).
+    # Excluded from `needs:`: `canvas-deploy-reminder` — it is an
+    # operational reminder, not a CI prerequisite. Keep that job runnable
+    # on PRs with an internal no-op guard; job-level event/ref `if:` gates
+    # are a Gitea 1.22.6 pending-status trap.
    #
    # Phase 3 (RFC #219 §1) safety: underlying build jobs carry
    # continue-on-error: true so their failures are masked to null (2026-05-12: re-enabled mc#774 interim)
@@ -559,7 +577,7 @@ jobs:
      - canvas-build
      - shellcheck
      - python-lint
-    if: always()
+    if: ${{ always() }}
    steps:
      - name: Assert every required dependency succeeded
        run: |
@@ -120,7 +120,7 @@ jobs:
        # no comment.user.login so the step is a no-op skip there.
        if: github.event_name == 'issue_comment'
        env:
-          GITEA_TOKEN: ${{ secrets.RFC_324_TEAM_READ_TOKEN || secrets.GITHUB_TOKEN }}
+          GITEA_TOKEN: ${{ secrets.SOP_TIER_CHECK_TOKEN || secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          login="${{ github.event.comment.user.login }}"
@@ -151,7 +151,7 @@ jobs:

      - name: Evaluate qa-review
        env:
-          GITEA_TOKEN: ${{ secrets.RFC_324_TEAM_READ_TOKEN || secrets.GITHUB_TOKEN }}
+          GITEA_TOKEN: ${{ secrets.SOP_TIER_CHECK_TOKEN || secrets.GITHUB_TOKEN }}
          GITEA_HOST: git.moleculesai.app
          REPO: ${{ github.repository }}
          # PR number lives in different places per event:
@@ -36,17 +36,19 @@ name: redeploy-tenants-on-main
 #
 # Runtime ordering:
 #   1. publish-workspace-server-image completes → new :staging-<sha> in ECR.
-#   2. This workflow fires via workflow_run, calls redeploy-fleet with
-#      target_tag=staging-<sha>. No CDN propagation wait needed —
-#      ECR image manifest is consistent immediately after push.
+#   2. The merge that updates publish-workspace-server-image.yml triggers
+#      this push/path-filtered workflow, which calls redeploy-fleet with
+#      target_tag=staging-<sha>. No CDN propagation wait needed — ECR image
+#      manifest is consistent immediately after push.
 #   3. Calls redeploy-fleet with canary_slug (if set) and a soak
 #      period. Canary proves the image boots; batches follow.
 #   4. Any failure aborts the rollout and leaves older tenants on the
 #      prior image — safer default than half-and-half state.
 #
-# Rollback path: re-run this workflow with a specific SHA pinned via
-# the workflow_dispatch input. That calls redeploy-fleet with
-# target_tag=<sha>, re-pulling the older image on every tenant.
+# Rollback path: set PROD_MANUAL_REDEPLOY_TARGET_TAG as a repo/org
+# variable or secret, run workflow_dispatch, then unset it after the
+# rollback. That calls redeploy-fleet with target_tag=<value>,
+# re-pulling the pinned image on every tenant.

 on:
  push:
@@ -77,13 +79,11 @@ env:
  GITHUB_SERVER_URL: https://git.moleculesai.app

 jobs:
+  # bp-exempt: production redeploy is a side-effect workflow, not a merge gate.
  redeploy:
-    # Skip the auto-trigger if publish-workspace-server-image didn't
-    # actually succeed. workflow_run fires on any completion state; we
-    # don't want to redeploy against a half-built image.
-    # NOTE (Gitea port): workflow_dispatch trigger dropped; only the
-    # workflow_run path remains.
-    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    # Gitea 1.22.6 does not support workflow_run. This workflow is now
+    # controlled by push/path triggers plus an explicit kill switch.
+    if: ${{ github.event_name == 'push' || github.event_name == 'workflow_dispatch' }}
    runs-on: ubuntu-latest
    # Phase 3 (RFC #219 §1): surface broken workflows without blocking.
    # mc#774: pre-existing continue-on-error mask; root-fix and remove, do not renew silently.
@@ -119,16 +119,16 @@ jobs:
        #      dead (staging-verify soft-skips without canary fleet, so
        #      the only thing retagging `:latest` today is the manual
        #      promote-latest.yml — last run 2026-04-28). Auto-trigger
-        #      from workflow_run uses workflow_run.head_sha; manual
-        #      dispatch with no input falls through to github.sha.
+        #      from the main push uses github.sha; manual
+        #      dispatch with no variable falls through to github.sha.
        env:
-          INPUT_TAG: ${{ inputs.target_tag }}
-          HEAD_SHA: ${{ github.event.workflow_run.head_sha || github.sha }}
+          PROD_MANUAL_REDEPLOY_TARGET_TAG: ${{ vars.PROD_MANUAL_REDEPLOY_TARGET_TAG || secrets.PROD_MANUAL_REDEPLOY_TARGET_TAG || '' }}
+          HEAD_SHA: ${{ github.sha }}
        run: |
          set -euo pipefail
-          if [ -n "${INPUT_TAG:-}" ]; then
-            echo "target_tag=$INPUT_TAG" >> "$GITHUB_OUTPUT"
-            echo "Using operator-pinned tag: $INPUT_TAG"
+          if [ -n "${PROD_MANUAL_REDEPLOY_TARGET_TAG:-}" ]; then
+            echo "target_tag=$PROD_MANUAL_REDEPLOY_TARGET_TAG" >> "$GITHUB_OUTPUT"
+            echo "Using operator-pinned tag from PROD_MANUAL_REDEPLOY_TARGET_TAG."
          else
            SHORT="${HEAD_SHA:0:7}"
            echo "target_tag=staging-$SHORT" >> "$GITHUB_OUTPUT"
@@ -144,13 +144,26 @@ jobs:
          CP_URL: ${{ vars.CP_URL || 'https://api.moleculesai.app' }}
          CP_ADMIN_API_TOKEN: ${{ secrets.CP_ADMIN_API_TOKEN }}
          TARGET_TAG: ${{ steps.tag.outputs.target_tag }}
-          CANARY_SLUG: ${{ inputs.canary_slug || 'hongming' }}
-          SOAK_SECONDS: ${{ inputs.soak_seconds || '60' }}
-          BATCH_SIZE: ${{ inputs.batch_size || '3' }}
-          DRY_RUN: ${{ inputs.dry_run || false }}
+          CANARY_SLUG: ${{ vars.PROD_REDEPLOY_CANARY_SLUG || secrets.PROD_REDEPLOY_CANARY_SLUG || '' }}
+          SOAK_SECONDS: ${{ vars.PROD_REDEPLOY_SOAK_SECONDS || secrets.PROD_REDEPLOY_SOAK_SECONDS || '' }}
+          BATCH_SIZE: ${{ vars.PROD_REDEPLOY_BATCH_SIZE || secrets.PROD_REDEPLOY_BATCH_SIZE || '' }}
+          DRY_RUN: ${{ vars.PROD_REDEPLOY_DRY_RUN || secrets.PROD_REDEPLOY_DRY_RUN || '' }}
+          PROD_AUTO_DEPLOY_DISABLED: ${{ vars.PROD_AUTO_DEPLOY_DISABLED || secrets.PROD_AUTO_DEPLOY_DISABLED || '' }}
        run: |
          set -euo pipefail

+          case "${PROD_AUTO_DEPLOY_DISABLED,,}" in
+            1|true|yes|on)
+              echo "::notice::PROD_AUTO_DEPLOY_DISABLED is set; skipping production redeploy."
+              exit 0
+              ;;
+          esac
+
+          CANARY_SLUG="${CANARY_SLUG:-hongming}"
+          SOAK_SECONDS="${SOAK_SECONDS:-60}"
+          BATCH_SIZE="${BATCH_SIZE:-3}"
+          DRY_RUN="${DRY_RUN:-false}"
+
          if [ -z "${CP_ADMIN_API_TOKEN:-}" ]; then
            echo "::error::CP_ADMIN_API_TOKEN secret not set — skipping redeploy"
            echo "::notice::Set CP_ADMIN_API_TOKEN in repo secrets to enable auto-redeploy."
@@ -172,7 +185,7 @@ jobs:
            }')

          echo "POST $CP_URL/cp/admin/tenants/redeploy-fleet"
-          echo "  body: $BODY"
+          echo "  target_tag=$TARGET_TAG canary=$CANARY_SLUG soak_seconds=$SOAK_SECONDS batch_size=$BATCH_SIZE dry_run=$DRY_RUN"

          HTTP_RESPONSE=$(mktemp)
          HTTP_CODE_FILE=$(mktemp)
@@ -281,10 +294,10 @@ jobs:
          if [ "$TARGET_TAG" != "latest" ] \
             && [ "$TARGET_TAG" != "$EXPECTED_SHA" ] \
             && [ "$TARGET_TAG" != "staging-$EXPECTED_SHORT" ]; then
-            # workflow_dispatch with a pinned tag that isn't the head
+            # Manual redeploy with a pinned tag that isn't the head
            # SHA — operator is rolling back / pinning. Skip the
            # verification because we don't have the expected SHA in
-            # this context (would need to crane-inspect the GHCR
+            # this context (would need to inspect the ECR
            # manifest, which is a follow-up). Failing-open here is
            # safe: the operator chose the tag deliberately.
            #
@@ -37,7 +37,7 @@ jobs:
        # so re-running on a non-collaborator comment is harmless.
        if: github.event_name == 'issue_comment'
        env:
-          GITEA_TOKEN: ${{ secrets.RFC_324_TEAM_READ_TOKEN || secrets.GITHUB_TOKEN }}
+          GITEA_TOKEN: ${{ secrets.SOP_TIER_CHECK_TOKEN || secrets.GITHUB_TOKEN }}
        run: |
          set -euo pipefail
          login="${{ github.event.comment.user.login }}"
@@ -62,7 +62,7 @@ jobs:

      - name: Evaluate security-review
        env:
-          GITEA_TOKEN: ${{ secrets.RFC_324_TEAM_READ_TOKEN || secrets.GITHUB_TOKEN }}
+          GITEA_TOKEN: ${{ secrets.SOP_TIER_CHECK_TOKEN || secrets.GITHUB_TOKEN }}
          GITEA_HOST: git.moleculesai.app
          REPO: ${{ github.repository }}
          PR_NUMBER: ${{ github.event.pull_request.number || github.event.issue.number }}
@@ -92,7 +92,8 @@ jobs:
      (github.event_name == 'issue_comment' &&
       github.event.issue.pull_request != null &&
       (contains(github.event.comment.body, '/sop-ack') ||
-        contains(github.event.comment.body, '/sop-revoke')))
+        contains(github.event.comment.body, '/sop-revoke') ||
+        contains(github.event.comment.body, '/sop-n/a')))
    runs-on: ubuntu-latest
    steps:
      - name: Check out BASE ref (trust boundary — never PR-head)
@@ -327,7 +327,7 @@ function OrgCTA({ org }: { org: Org }) {
    return (
      <a
        href={href}
-        className="rounded bg-emerald-600 px-4 py-2 text-sm font-medium text-white hover:bg-emerald-500"
+        className="rounded bg-emerald-700 px-4 py-2 text-sm font-medium text-white hover:bg-emerald-600"
      >
        Open
      </a>
@@ -337,7 +337,7 @@ function OrgCTA({ org }: { org: Org }) {
    return (
      <a
        href={`/pricing?org=${encodeURIComponent(org.slug)}`}
-        className="rounded bg-amber-600 px-4 py-2 text-sm font-medium text-white hover:bg-amber-500"
+        className="rounded bg-amber-800 px-4 py-2 text-sm font-medium text-white hover:bg-amber-700"
      >
        Complete payment
      </a>
@@ -164,7 +164,10 @@ export function AuditTrailPanel({ workspaceId }: Props) {

      {/* Error banner */}
      {error && (
-        <div className="mx-4 mt-3 px-3 py-2 bg-red-950/30 border border-red-800/40 rounded text-xs text-bad shrink-0">
+        <div
+          role="alert"
+          className="mx-4 mt-3 px-3 py-2 bg-red-950/30 border border-red-800/40 rounded text-xs text-bad shrink-0"
+        >
          {error}
        </div>
      )}
@@ -96,7 +96,7 @@ export function ConfirmDialog({
  // readable in both light and dark themes.
  const confirmColors =
    confirmVariant === "danger"
-      ? "bg-red-600 hover:bg-red-700 text-white"
+      ? "bg-red-700 hover:bg-red-600 text-white"
      : confirmVariant === "warning"
        ? "bg-amber-800 hover:bg-amber-700 text-white"
        : "bg-accent hover:bg-accent-strong text-white";
@@ -1,6 +1,6 @@
 "use client";

-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useCanvasStore, type WorkspaceNodeData } from "@/store/canvas";
 import { api } from "@/lib/api";
 import { showToast } from "./Toaster";
@@ -23,9 +23,17 @@ export function ContextMenu() {
  const setPanelTab = useCanvasStore((s) => s.setPanelTab);
  const nestNode = useCanvasStore((s) => s.nestNode);
  const contextNodeId = contextMenu?.nodeId ?? null;
-  const hasChildren = useCanvasStore((s) =>
-    contextNodeId ? s.nodes.some((n) => n.data.parentId === contextNodeId) : false
+  // Select the full nodes array (stable reference across unrelated store
+  // updates) and derive children via useMemo. Filtering inside the
+  // selector returned a new array every call, which Zustand's
+  // useSyncExternalStore saw as "snapshot changed" → schedule
+  // re-render → loop → React error #185. See canvas-store-snapshots.
+  const nodes = useCanvasStore((s) => s.nodes);
+  const children = useMemo(
+    () => (contextNodeId ? nodes.filter((n) => n.data.parentId === contextNodeId) : []),
+    [nodes, contextNodeId],
  );
+  const hasChildren = children.length > 0;
  const setPendingDelete = useCanvasStore((s) => s.setPendingDelete);
  const ref = useRef<HTMLDivElement>(null);
  const [actionLoading, setActionLoading] = useState(false);
@@ -189,10 +197,9 @@ export function ContextMenu() {
    // it survives ContextMenu unmount. Closing the menu here avoids the
    // prior race where the portal dialog's Confirm click was treated as
    // "outside" by the menu's outside-click handler.
-    const childNodes = useCanvasStore.getState().nodes.filter((n) => n.data.parentId === contextMenu.nodeId);
-    setPendingDelete({ id: contextMenu.nodeId, name: contextMenu.nodeData.name, hasChildren, children: childNodes.map(c => ({ id: c.id, name: c.data.name })) });
+    setPendingDelete({ id: contextMenu.nodeId, name: contextMenu.nodeData.name, hasChildren, children: children.map(c => ({ id: c.id, name: c.data.name })) });
    closeContextMenu();
-  }, [contextMenu, setPendingDelete, closeContextMenu]);
+  }, [contextMenu, setPendingDelete, closeContextMenu, children, hasChildren]);

  const handleViewDetails = useCallback(() => {
    if (!contextMenu) return;
@@ -164,12 +164,12 @@ export function DeleteCascadeConfirmDialog({
            type="button"
            onClick={onConfirm}
            disabled={!checked}
-            // 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.
+            // Hover goes DARKER, not lighter — bg-red-600 on white text
+            // drops contrast below AA. Same trap fixed in ConfirmDialog.
+            // focus-visible ring matches the canvas chrome.
            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-700 text-white cursor-pointer"
+                ? "bg-red-700 hover:bg-red-600 text-white cursor-pointer"
                : "bg-red-900/30 text-bad/40 cursor-not-allowed"
              }`}
          >
@@ -51,7 +51,7 @@ export class ErrorBoundary extends React.Component<
  render() {
    if (this.state.hasError) {
      return (
-        <div className="fixed inset-0 flex items-center justify-center bg-surface z-50">
+        <div role="alert" aria-live="assertive" className="fixed inset-0 flex items-center justify-center bg-surface z-50">
          <div className="max-w-md rounded-2xl border border-red-500/30 bg-surface-sunken/90 px-8 py-8 text-center shadow-2xl shadow-black/40">
            <div className="mx-auto mb-4 flex h-14 w-14 items-center justify-center rounded-full bg-red-500/10 border border-red-500/30">
              <svg
@@ -389,7 +389,7 @@ export function ProvisioningTimeout({
              <button
                type="button"
                onClick={handleCancelConfirm}
-                className="px-3.5 py-1.5 text-[12px] bg-red-600 hover:bg-red-500 text-white rounded-lg transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-400 focus-visible:ring-offset-1"
+                className="px-3.5 py-1.5 text-[12px] bg-red-800 hover:bg-red-700 text-white rounded-lg transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-400 focus-visible:ring-offset-1"
              >
                Remove Workspace
              </button>
@@ -398,3 +398,78 @@ describe("ContextMenu — item actions", () => {
    expect(mockPost).toHaveBeenCalledWith("/workspaces/n1/resume", {});
  });
 });
+
+/**
+ * Regression tests for GitHub issue #651 — React error #185:
+ * "Maximum update depth exceeded" on Chat tab / mobile.
+ *
+ * Root cause: ContextMenu's children selector ran `.filter()` inside the
+ * Zustand hook, returning a brand-new array reference on every render.
+ * Zustand's useSyncExternalStore compared snapshots with Object.is —
+ * a new array always differs — so React kept scheduling re-renders,
+ * hit the 50-update depth cap, and crashed.
+ *
+ * Fix: select the stable `nodes` array once, derive children via
+ * useMemo outside the store subscription.
+ */
+describe("ContextMenu — hasChildren regression (GitHub #651)", () => {
+  beforeEach(() => { setupApiMocks(); });
+  afterEach(() => {
+    cleanup();
+    vi.clearAllMocks();
+    mockStoreState.contextMenu = null;
+    mockStoreState.closeContextMenu.mockClear();
+    mockStoreState.updateNodeData.mockClear();
+    mockStoreState.selectNode.mockClear();
+    mockStoreState.setPanelTab.mockClear();
+    mockStoreState.nestNode.mockClear();
+    mockStoreState.setPendingDelete.mockClear();
+    mockStoreState.setCollapsed.mockClear();
+    mockStoreState.arrangeChildren.mockClear();
+    mockStoreState.nodes = [];
+    resetApiMocks();
+    vi.mocked(showToast).mockClear();
+  });
+
+  it("setPendingDelete receives correct children array when workspace has children", () => {
+    openMenu({ nodeId: "ws-parent", nodeData: { name: "Parent", status: "online", tier: 4, role: "assistant" } });
+    mockStoreState.nodes = [
+      { id: "ws-child-a", data: { parentId: "ws-parent" } },
+      { id: "ws-child-b", data: { parentId: "ws-parent" } },
+    ];
+    render(<ContextMenu />);
+    const deleteBtn = screen.getAllByRole("menuitem").find((el) =>
+      el.textContent?.includes("Delete")
+    )!;
+    fireEvent.click(deleteBtn);
+    expect(mockStoreState.setPendingDelete).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "ws-parent",
+        name: "Parent",
+        hasChildren: true,
+        children: [
+          { id: "ws-child-a", name: undefined },
+          { id: "ws-child-b", name: undefined },
+        ],
+      })
+    );
+  });
+
+  it("setPendingDelete hasChildren=false and empty children array when workspace has no children", () => {
+    openMenu({ nodeId: "ws-leaf", nodeData: { name: "Leaf", status: "online", tier: 4, role: "assistant" } });
+    mockStoreState.nodes = [];
+    render(<ContextMenu />);
+    const deleteBtn = screen.getAllByRole("menuitem").find((el) =>
+      el.textContent?.includes("Delete")
+    )!;
+    fireEvent.click(deleteBtn);
+    expect(mockStoreState.setPendingDelete).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: "ws-leaf",
+        name: "Leaf",
+        hasChildren: false,
+        children: [],
+      })
+    );
+  });
+});
@@ -75,7 +75,7 @@ export function DropTargetBadge() {
      )}
      <div
        data-testid="drop-badge"
-        className="pointer-events-none absolute z-50 -translate-x-1/2 -translate-y-full rounded-md bg-emerald-500 px-2 py-0.5 text-[11px] font-medium text-white shadow-lg shadow-emerald-950/40"
+        className="pointer-events-none absolute z-50 -translate-x-1/2 -translate-y-full rounded-md bg-emerald-700 px-2 py-0.5 text-[11px] font-medium text-white shadow-lg shadow-emerald-950/40"
        style={{ left: badge.x, top: badge.y - 6 }}
      >
        Drop into: {targetName}
@@ -1011,11 +1011,10 @@ function MyChatPanel({ workspaceId, data }: Props) {
            <div
              className={`max-w-[85%] rounded-lg px-3 py-2 text-xs ${
                msg.role === "user"
-                  // 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"
+                  // Blue-600 on white = 3.0:1 (WCAG AA FAIL) in light mode.
+                  // Blue-700 on white = 4.5:1 (PASS). In dark mode, blue-600
+                  // on zinc-800 = 4.9:1 (PASS). So: blue-700 light, blue-600 dark.
+                  ? "bg-blue-700 text-white border border-blue-800 dark:bg-blue-600 dark:border-blue-700 shadow-sm"
                  : msg.role === "system"
                    // Bump the system bubble's opacity in dark — /10
                    // overlay was nearly invisible against the dark
@@ -325,10 +325,10 @@ export function DetailsTab({ workspaceId, data }: Props) {
              <button
                type="button"
                onClick={handleDelete}
-                // 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"
+                // Red-600 on white text = 3.9:1 (WCAG AA FAIL).
+                // Red-700 = 4.6:1 (PASS). Hover goes DARKER (red-600)
+                // to signal press. Same pattern as ConfirmDialog/DeleteCascade.
+                className="px-3 py-1 bg-red-700 hover:bg-red-600 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>
@@ -131,7 +131,7 @@ export function ExternalConnectionSection({ workspaceId }: Props) {
              <button
                type="button"
                onClick={doRotate}
-                className="px-3 py-1.5 bg-red-700 hover:bg-red-600 text-xs rounded text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-500 focus-visible:ring-offset-1"
+                className="px-3 py-1.5 bg-red-800 hover:bg-red-700 text-xs rounded text-white focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-red-500 focus-visible:ring-offset-1"
              >
                Rotate
              </button>
@@ -1,217 +1,182 @@
 // @vitest-environment jsdom
 /**
- * FilesTab: NotAvailablePanel + FilesToolbar coverage.
+ * Tests for the main FilesTab / PlatformOwnedFilesTab component.
 *
- * NotAvailablePanel: pure presentational component — renders a "feature not
- * available" placeholder for external-runtime workspaces.
- * FilesToolbar: pure props-driven component — directory selector, file count,
- * action buttons (New, Upload, Export, Clear, Refresh) with correct aria-labels.
+ * Covers: NotAvailablePanel (external runtime), loading/empty/error states,
+ * FilesToolbar actions, and the /configs-only upload guard.
 *
- * No @testing-library/jest-dom import — use textContent / className /
- * getAttribute checks to avoid "expect is not defined" errors.
+ * No @testing-library/jest-dom — use textContent / className / getAttribute.
 */
 import { afterEach, describe, expect, it, vi } from "vitest";
-import { cleanup, render, screen } from "@testing-library/react";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
 import React from "react";

 import { FilesToolbar } from "../FilesToolbar";
-import { NotAvailablePanel } from "../NotAvailablePanel";
+import { FilesTab } from "../../FilesTab.tsx";
+import type { FileEntry } from "../../FilesTab/tree";

-// ─── afterEach ─────────────────────────────────────────────────────────────────
+// ─── Mock ──────────────────────────────────────────────────────────────────
+
+const _mockGet = vi.hoisted(() => vi.fn<() => Promise<unknown>>());
+vi.mock("@/lib/api", () => ({
+  api: { get: _mockGet, put: vi.fn(), del: vi.fn() },
+}));

 afterEach(() => {
  cleanup();
-  vi.restoreAllMocks();
+  _mockGet.mockReset();
 });

-// ─── NotAvailablePanel ─────────────────────────────────────────────────────────
+// ─── Helpers ───────────────────────────────────────────────────────────────

-describe("NotAvailablePanel", () => {
-  it("renders heading 'Files not available'", () => {
-    const { container } = render(<NotAvailablePanel runtime="external" />);
-    expect(container.textContent).toContain("Files not available");
-  });
+const emptyFileList: FileEntry[] = [];

-  it("renders the runtime name in monospace", () => {
-    const { container } = render(<NotAvailablePanel runtime="external" />);
-    expect(container.textContent).toContain("external");
-    const spans = container.querySelectorAll("span");
-    const monoSpans = Array.from(spans).filter(
-      (s) => s.className && s.className.includes("font-mono"),
-    );
-    expect(monoSpans.length).toBeGreaterThan(0);
-  });
-
-  it("renders a Chat tab hint in description", () => {
-    const { container } = render(<NotAvailablePanel runtime="remote-agent" />);
-    expect(container.textContent).toContain("Chat tab");
-  });
-
-  it("SVG icon has aria-hidden=true", () => {
-    const { container } = render(<NotAvailablePanel runtime="external" />);
-    const svg = container.querySelector("svg");
-    expect(svg?.getAttribute("aria-hidden")).toBe("true");
-  });
-
-  it("renders without crashing for any runtime string", () => {
-    const { container } = render(<NotAvailablePanel runtime="unknown-runtime" />);
-    expect(container.textContent).toContain("unknown-runtime");
-  });
-
-  it("applies the correct layout classes to root div", () => {
-    const { container } = render(<NotAvailablePanel runtime="external" />);
-    const root = container.firstElementChild as HTMLElement;
-    expect(root.className).toContain("flex");
-    expect(root.className).toContain("flex-col");
-    expect(root.className).toContain("items-center");
-  });
-});
-
-// ─── FilesToolbar ───────────────────────────────────────────────────────────────
-
-describe("FilesToolbar", () => {
+/** Render FilesToolbar directly — used by the focus-visible accessibility test. */
+function renderToolbar(props: Partial<React.ComponentProps<typeof FilesToolbar>> = {}) {
  const noop = vi.fn();
+  return render(
+    <FilesToolbar
+      root="/configs"
+      setRoot={noop}
+      fileCount={0}
+      onNewFile={noop}
+      onUpload={noop}
+      onDownloadAll={noop}
+      onClearAll={noop}
+      onRefresh={noop}
+      {...props}
+    />,
+  );
+}

-  function renderToolbar(props: Partial<React.ComponentProps<typeof FilesToolbar>> = {}) {
-    return render(
-      <FilesToolbar
-        root="/configs"
-        setRoot={noop}
-        fileCount={0}
-        onNewFile={noop}
-        onUpload={noop}
-        onDownloadAll={noop}
-        onClearAll={noop}
-        onRefresh={noop}
-        {...props}
+/** Render FilesTab with a non-external runtime (triggers PlatformOwnedFilesTab). */
+function renderPlatformTab(extraProps: Partial<React.ComponentProps<typeof FilesTab>> = {}) {
+  return render(
+    <FilesTab
+      workspaceId="ws-1"
+      data={{ id: "ws-1", name: "Test", runtime: "claude-code", status: "online", tier: 0, skills: [], created_at: "" }}
+      {...extraProps}
+    />,
+  );
+}
+
+// ─── NotAvailablePanel ──────────────────────────────────────────────────────
+
+describe("FilesTab — NotAvailablePanel", () => {
+  it("renders NotAvailablePanel when runtime is external", async () => {
+    _mockGet.mockResolvedValueOnce(emptyFileList);
+    render(
+      <FilesTab
+        workspaceId="ws-1"
+        data={{ id: "ws-1", name: "Test", runtime: "external", status: "online", tier: 0, skills: [], created_at: "" }}
      />,
    );
-  }
-
-  it("renders the directory selector with correct aria-label", () => {
-    const { container } = renderToolbar();
-    const select = container.querySelector("select");
-    expect(select?.getAttribute("aria-label")).toBe("File root directory");
+    expect(screen.getByText(/Files not available/i)).toBeTruthy();
  });

-  it("directory selector has all four options", () => {
-    const { container } = renderToolbar();
-    const select = container.querySelector("select") as HTMLSelectElement;
-    const options = Array.from(select?.options ?? []);
-    const values = options.map((o) => o.value);
-    expect(values).toContain("/configs");
-    expect(values).toContain("/home");
-    expect(values).toContain("/workspace");
-    expect(values).toContain("/plugins");
-  });
-
-  it("calls setRoot when directory changes", () => {
-    const setRoot = vi.fn();
-    const { container } = renderToolbar({ setRoot });
-    const select = container.querySelector("select") as HTMLSelectElement;
-    select.value = "/home";
-    select.dispatchEvent(new Event("change", { bubbles: true }));
-    expect(setRoot).toHaveBeenCalledWith("/home");
-  });
-
-  it("displays the file count", () => {
-    const { container } = renderToolbar({ fileCount: 42 });
-    expect(container.textContent).toContain("42 files");
-  });
-
-  it("shows New + Upload + Clear buttons for /configs", () => {
-    const { container } = renderToolbar({ root: "/configs" });
-    const texts = Array.from(container.querySelectorAll("button")).map(
-      (b) => b.textContent?.trim(),
+  it("renders the runtime name in NotAvailablePanel", async () => {
+    _mockGet.mockResolvedValueOnce(emptyFileList);
+    render(
+      <FilesTab
+        workspaceId="ws-1"
+        data={{ id: "ws-1", name: "Test", runtime: "external", status: "online", tier: 0, skills: [], created_at: "" }}
+      />,
    );
-    expect(texts).toContain("+ New");
-    expect(texts).toContain("Upload");
-    expect(texts).toContain("Clear");
-    expect(texts).toContain("Export");
-    expect(texts).toContain("↻");
+    expect(screen.getByText(/external/i)).toBeTruthy();
  });

-  it("hides New + Upload + Clear for /workspace", () => {
-    const { container } = renderToolbar({ root: "/workspace" });
-    const texts = Array.from(container.querySelectorAll("button")).map(
-      (b) => b.textContent?.trim(),
+  it("does NOT call api.get when runtime is external", async () => {
+    render(
+      <FilesTab
+        workspaceId="ws-1"
+        data={{ id: "ws-1", name: "Test", runtime: "external", status: "online", tier: 0, skills: [], created_at: "" }}
+      />,
    );
-    expect(texts).not.toContain("+ New");
-    expect(texts).not.toContain("Upload");
-    expect(texts).not.toContain("Clear");
-    expect(texts).toContain("Export");
+    expect(_mockGet).not.toHaveBeenCalled();
  });
+});

-  it("hides New + Upload + Clear for /home", () => {
-    const { container } = renderToolbar({ root: "/home" });
-    const texts = Array.from(container.querySelectorAll("button")).map(
-      (b) => b.textContent?.trim(),
+// ─── Loading / Empty / Error states ────────────────────────────────────────
+
+describe("FilesTab — states", () => {
+  it("shows loading text while fetching files", () => {
+    _mockGet.mockImplementation(
+      () => new Promise<unknown>(() => {}) as unknown as Promise<unknown>,
    );
-    expect(texts).not.toContain("+ New");
-    expect(texts).not.toContain("Upload");
-    expect(texts).not.toContain("Clear");
+    renderPlatformTab();
+    expect(screen.getByText("Loading files...")).toBeTruthy();
  });

-  it("hides New + Upload + Clear for /plugins", () => {
-    const { container } = renderToolbar({ root: "/plugins" });
-    const texts = Array.from(container.querySelectorAll("button")).map(
-      (b) => b.textContent?.trim(),
-    );
-    expect(texts).not.toContain("+ New");
-    expect(texts).not.toContain("Upload");
-    expect(texts).not.toContain("Clear");
+  it("shows 'No config files yet' when root is /configs and no files", async () => {
+    _mockGet.mockResolvedValueOnce(emptyFileList);
+    renderPlatformTab();
+    await waitFor(() => {
+      expect(screen.getByText(/No config files yet/i)).toBeTruthy();
+    });
  });

-  it("New button has correct aria-label", () => {
-    const { container } = renderToolbar({ root: "/configs" });
-    const newBtn = container.querySelector('button[aria-label="Create new file"]');
-    expect(newBtn?.textContent?.trim()).toBe("+ New");
+  it("fetches from the correct endpoint", async () => {
+    _mockGet.mockResolvedValueOnce(emptyFileList);
+    renderPlatformTab();
+    await waitFor(() => {
+      expect(_mockGet).toHaveBeenCalledWith(expect.stringContaining("/workspaces/ws-1/files"));
+    });
  });

-  it("Export button has correct aria-label", () => {
-    const { container } = renderToolbar();
-    const exportBtn = container.querySelector('button[aria-label="Download all files"]');
-    expect(exportBtn?.textContent?.trim()).toBe("Export");
+  it("shows file count from toolbar when files exist", async () => {
+    _mockGet.mockResolvedValue([
+      { path: "configs/a.yaml", size: 10, dir: false },
+      { path: "configs/b.yaml", size: 20, dir: false },
+    ]);
+    renderPlatformTab();
+    await waitFor(() => {
+      expect(screen.getByText("2 files")).toBeTruthy();
+    });
+  });
+});
+
+// ─── FilesToolbar ──────────────────────────────────────────────────────────
+
+describe("FilesTab — FilesToolbar", () => {
+  it("shows Refresh button", async () => {
+    _mockGet.mockResolvedValueOnce(emptyFileList);
+    renderPlatformTab();
+    await waitFor(() => {
+      expect(screen.getByLabelText("Refresh file list")).toBeTruthy();
+    });
  });

-  it("Clear button has correct aria-label", () => {
-    const { container } = renderToolbar({ root: "/configs" });
-    const clearBtn = container.querySelector('button[aria-label="Delete all files"]');
-    expect(clearBtn?.textContent?.trim()).toBe("Clear");
+  it("shows root directory selector", async () => {
+    _mockGet.mockResolvedValueOnce(emptyFileList);
+    renderPlatformTab();
+    await waitFor(() => {
+      expect(screen.getByRole("combobox")).toBeTruthy();
+    });
  });

-  it("Refresh button has correct aria-label", () => {
-    const { container } = renderToolbar();
-    const refreshBtn = container.querySelector('button[aria-label="Refresh file list"]');
-    expect(refreshBtn?.textContent?.trim()).toBe("↻");
+  it("Refresh button triggers a reload", async () => {
+    // Use persistent mock — loadFiles fires on mount AND on Refresh click.
+    _mockGet.mockResolvedValue(emptyFileList);
+    renderPlatformTab();
+    await waitFor(() => screen.getByLabelText("Refresh file list"));
+    const before = _mockGet.mock.calls.length;
+    fireEvent.click(screen.getByLabelText("Refresh file list"));
+    await waitFor(() => {
+      expect(_mockGet.mock.calls.length).toBeGreaterThan(before);
+    });
  });
+});

-  it("calls onNewFile when New button is clicked", () => {
-    const onNewFile = vi.fn();
-    const { container } = renderToolbar({ root: "/configs", onNewFile });
-    container.querySelector('button[aria-label="Create new file"]')!.click();
-    expect(onNewFile).toHaveBeenCalledTimes(1);
-  });
+// ─── Upload guard ──────────────────────────────────────────────────────────

-  it("calls onDownloadAll when Export button is clicked", () => {
-    const onDownloadAll = vi.fn();
-    const { container } = renderToolbar({ onDownloadAll });
-    container.querySelector('button[aria-label="Download all files"]')!.click();
-    expect(onDownloadAll).toHaveBeenCalledTimes(1);
-  });
+describe("FilesTab — upload guard", () => {
+  it("no error alert on dragover when root is /configs (default)", async () => {
+    _mockGet.mockResolvedValue(emptyFileList);
+    renderPlatformTab();
+    await waitFor(() => screen.getByText(/No config files yet/i));

-  it("calls onClearAll when Clear button is clicked", () => {
-    const onClearAll = vi.fn();
-    const { container } = renderToolbar({ root: "/configs", onClearAll });
-    container.querySelector('button[aria-label="Delete all files"]')!.click();
-    expect(onClearAll).toHaveBeenCalledTimes(1);
-  });
-
-  it("calls onRefresh when Refresh button is clicked", () => {
-    const onRefresh = vi.fn();
-    const { container } = renderToolbar({ onRefresh });
-    container.querySelector('button[aria-label="Refresh file list"]')!.click();
-    expect(onRefresh).toHaveBeenCalledTimes(1);
+    // No alert should be present
+    expect(screen.queryByRole("alert")).toBeNull();
  });

  it("applies focus-visible ring to all interactive buttons", () => {
@@ -0,0 +1,218 @@
+// @vitest-environment jsdom
+/**
+ * Tests for tree.ts — buildTree and getIcon pure functions.
+ */
+import { describe, expect, it } from "vitest";
+import type { FileEntry } from "../tree";
+import { buildTree, getIcon } from "../tree";
+
+// ─── getIcon ─────────────────────────────────────────────────────────────────
+
+describe("getIcon", () => {
+  it("returns folder emoji for directories", () => {
+    expect(getIcon("/configs", true)).toBe("📁");
+  });
+
+  it("returns correct emoji for .md", () => {
+    expect(getIcon("readme.md", false)).toBe("📄");
+  });
+
+  it("returns correct emoji for .yaml", () => {
+    expect(getIcon("config.yaml", false)).toBe("⚙");
+  });
+
+  it("returns correct emoji for .yml", () => {
+    expect(getIcon("config.yml", false)).toBe("⚙");
+  });
+
+  it("returns correct emoji for .py", () => {
+    expect(getIcon("script.py", false)).toBe("🐍");
+  });
+
+  it("returns correct emoji for .ts", () => {
+    expect(getIcon("index.ts", false)).toBe("💠");
+  });
+
+  it("returns correct emoji for .tsx", () => {
+    expect(getIcon("App.tsx", false)).toBe("💠");
+  });
+
+  it("returns correct emoji for .js", () => {
+    expect(getIcon("index.js", false)).toBe("📜");
+  });
+
+  it("returns correct emoji for .json", () => {
+    expect(getIcon("package.json", false)).toBe("{}");
+  });
+
+  it("returns correct emoji for .html", () => {
+    expect(getIcon("index.html", false)).toBe("🌐");
+  });
+
+  it("returns correct emoji for .css", () => {
+    expect(getIcon("style.css", false)).toBe("🎨");
+  });
+
+  it("returns correct emoji for .sh", () => {
+    expect(getIcon("deploy.sh", false)).toBe("▸");
+  });
+
+  it("returns default file emoji for unknown extensions", () => {
+    expect(getIcon("Makefile", false)).toBe("📄");
+    expect(getIcon("Dockerfile", false)).toBe("📄");
+    expect(getIcon("Rakefile", false)).toBe("📄");
+  });
+
+  it("extension matching is case-insensitive", () => {
+    expect(getIcon("readme.MD", false)).toBe("📄");
+    expect(getIcon("script.PY", false)).toBe("🐍");
+  });
+});
+
+// ─── buildTree ───────────────────────────────────────────────────────────────
+
+describe("buildTree", () => {
+  it("returns empty array for empty input", () => {
+    expect(buildTree([])).toEqual([]);
+  });
+
+  it("adds a single file at root", () => {
+    const files: FileEntry[] = [{ path: "config.yaml", size: 128, dir: false }];
+    const tree = buildTree(files);
+    expect(tree).toHaveLength(1);
+    expect(tree[0]).toMatchObject({
+      name: "config.yaml",
+      path: "config.yaml",
+      isDir: false,
+      children: [],
+      size: 128,
+    });
+  });
+
+  it("adds a single directory at root", () => {
+    const files: FileEntry[] = [{ path: "skills", size: 0, dir: true }];
+    const tree = buildTree(files);
+    expect(tree).toHaveLength(1);
+    expect(tree[0]).toMatchObject({
+      name: "skills",
+      path: "skills",
+      isDir: true,
+      children: [],
+      size: 0,
+    });
+  });
+
+  it("sorts dirs before files at the same level", () => {
+    const files: FileEntry[] = [
+      { path: "b.txt", size: 10, dir: false },
+      { path: "a.txt", size: 10, dir: false },
+      { path: "z-dir", size: 0, dir: true },
+      { path: "a-dir", size: 0, dir: true },
+    ];
+    const tree = buildTree(files);
+    expect(tree).toHaveLength(4);
+    // Dirs first: z-dir, a-dir alphabetically → a before z
+    expect(tree[0].name).toBe("a-dir");
+    expect(tree[1].name).toBe("z-dir");
+    // Then files alphabetically
+    expect(tree[2].name).toBe("a.txt");
+    expect(tree[3].name).toBe("b.txt");
+  });
+
+  it("alphabetically sorts files within the same level", () => {
+    const files: FileEntry[] = [
+      { path: "z.yaml", size: 10, dir: false },
+      { path: "a.yaml", size: 10, dir: false },
+      { path: "m.yaml", size: 10, dir: false },
+    ];
+    const tree = buildTree(files);
+    expect(tree.map((n) => n.name)).toEqual(["a.yaml", "m.yaml", "z.yaml"]);
+  });
+
+  it("nests a file under its parent directory", () => {
+    const files: FileEntry[] = [
+      { path: "skills", size: 0, dir: true },
+      { path: "skills/readme.md", size: 64, dir: false },
+    ];
+    const tree = buildTree(files);
+    expect(tree).toHaveLength(1);
+    expect(tree[0].name).toBe("skills");
+    expect(tree[0].children).toHaveLength(1);
+    expect(tree[0].children[0]).toMatchObject({
+      name: "readme.md",
+      path: "skills/readme.md",
+      isDir: false,
+      size: 64,
+    });
+  });
+
+  it("creates intermediate directories automatically", () => {
+    const files: FileEntry[] = [
+      { path: "a/b/c/deep.txt", size: 32, dir: false },
+    ];
+    const tree = buildTree(files);
+    // Root has one child: "a"
+    expect(tree).toHaveLength(1);
+    expect(tree[0].name).toBe("a");
+    expect(tree[0].isDir).toBe(true);
+    // "a" has one child: "b"
+    expect(tree[0].children).toHaveLength(1);
+    expect(tree[0].children[0].name).toBe("b");
+    // "b" has one child: "c"
+    expect(tree[0].children[0].children).toHaveLength(1);
+    expect(tree[0].children[0].children[0].name).toBe("c");
+    // "c" has the file
+    expect(tree[0].children[0].children[0].children[0].name).toBe("deep.txt");
+    expect(tree[0].children[0].children[0].children[0].size).toBe(32);
+  });
+
+  it("adds multiple files to the same directory", () => {
+    const files: FileEntry[] = [
+      { path: "configs", size: 0, dir: true },
+      { path: "configs/a.yaml", size: 10, dir: false },
+      { path: "configs/b.yaml", size: 20, dir: false },
+    ];
+    const tree = buildTree(files);
+    expect(tree).toHaveLength(1);
+    expect(tree[0].children.map((n) => n.name).sort()).toEqual(["a.yaml", "b.yaml"]);
+  });
+
+  it("does not duplicate a directory already created as intermediate", () => {
+    const files: FileEntry[] = [
+      { path: "a/b.txt", size: 5, dir: false },
+      { path: "a", size: 0, dir: true },
+    ];
+    const tree = buildTree(files);
+    // "a" should appear only once
+    expect(tree).toHaveLength(1);
+    expect(tree[0].name).toBe("a");
+    // The dir "a" should still contain "b.txt"
+    expect(tree[0].children).toHaveLength(1);
+    expect(tree[0].children[0].name).toBe("b.txt");
+  });
+
+  it("intermediate dirs have size 0", () => {
+    const files: FileEntry[] = [
+      { path: "a/b/c/file.txt", size: 1, dir: false },
+    ];
+    const tree = buildTree(files);
+    expect(tree[0].size).toBe(0);
+    expect(tree[0].children[0].size).toBe(0);
+  });
+
+  it("handles deeply nested mixed dirs and files", () => {
+    const files: FileEntry[] = [
+      { path: "a", size: 0, dir: true },
+      { path: "a/b", size: 0, dir: true },
+      { path: "a/b/c", size: 0, dir: true },
+      { path: "a/b/c/d.txt", size: 1, dir: false },
+      { path: "a/b/e.txt", size: 2, dir: false },
+      { path: "a/f.txt", size: 3, dir: false },
+    ];
+    const tree = buildTree(files);
+    expect(tree).toHaveLength(1); // root: "a"
+    expect(tree[0].children.map((n) => n.name).sort()).toEqual(["b", "f.txt"]);
+    expect(tree[0].children.find((n) => n.name === "b")!.children.map((n) => n.name).sort())
+      .toEqual(["c", "e.txt"]);
+  });
+});
@@ -0,0 +1,60 @@
+/**
+ * Tests for `isExternalLikeRuntime` — mirrors the backend's
+ * isExternalLikeRuntime() in workspace-server/internal/handlers/runtime_registry.go.
+ *
+ * These runtimes have no platform-owned container (no Files, Terminal, Docker config).
+ * Both frontend and backend must agree on which runtimes are "external-like" so
+ * the canvas can show/hide those tabs correctly and the backend can enforce
+ * the same semantics server-side.
+ */
+import { describe, it, expect } from "vitest";
+import { isExternalLikeRuntime } from "../externalRuntimes";
+
+describe("isExternalLikeRuntime", () => {
+  describe("known external-like runtimes", () => {
+    it.each([
+      ["external"],
+      ["kimi"],
+      ["kimi-cli"],
+    ])("%q returns true", (runtime) => {
+      expect(isExternalLikeRuntime(runtime)).toBe(true);
+    });
+  });
+
+  describe("non-external runtimes", () => {
+    it.each([
+      "claude-code",
+      "hermes",
+      "docker",
+      "local",
+      "agent",
+      "crewai",
+      "langgraph",
+      "openclaw",
+      "custom-runtime",
+    ])("%q returns false", (runtime) => {
+      expect(isExternalLikeRuntime(runtime)).toBe(false);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("returns false for undefined", () => {
+      expect(isExternalLikeRuntime(undefined)).toBe(false);
+    });
+
+    it("returns false for null", () => {
+      // @ts-expect-error — intentional runtime test, null is not a valid type
+      expect(isExternalLikeRuntime(null)).toBe(false);
+    });
+
+    it("returns false for empty string", () => {
+      expect(isExternalLikeRuntime("")).toBe(false);
+    });
+
+    it("is case-sensitive — kimi vs KIMI vs Kimi", () => {
+      expect(isExternalLikeRuntime("KIMI")).toBe(false);
+      expect(isExternalLikeRuntime("Kimi")).toBe(false);
+      expect(isExternalLikeRuntime("kimi")).toBe(true);
+    });
+  });
+});
@@ -0,0 +1,189 @@
+// @vitest-environment jsdom
+/**
+ * Tests for hydrate.ts — canvas store hydration with exponential backoff.
+ *
+ * Covers:
+ *   - Successful hydration on first attempt (no retries)
+ *   - Retry with exponential backoff on failure
+ *   - onRetrying callback called at correct intervals
+ *   - Error propagation after MAX_RETRIES exhausted
+ *   - Viewport persisted on success
+ *   - Viewport failure is non-fatal
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { WorkspaceData } from "@/store/socket";
+
+// ---------------------------------------------------------------------------
+// Mock modules — must precede imports that use them
+// ---------------------------------------------------------------------------
+
+const mockHydrate = vi.fn();
+const mockSetViewport = vi.fn();
+
+vi.mock("@/lib/api", () => ({
+  api: {
+    get: vi.fn(),
+  },
+  PLATFORM_URL: "https://platform.test",
+}));
+
+vi.mock("@/store/canvas", () => ({
+  useCanvasStore: Object.assign(
+    () => ({}),
+    {
+      getState: () => ({
+        hydrate: mockHydrate,
+        setViewport: mockSetViewport,
+      }),
+    },
+  ),
+}));
+
+// ---------------------------------------------------------------------------
+// Import after mocks
+// ---------------------------------------------------------------------------
+
+import { api } from "@/lib/api";
+import { hydrateCanvas, MAX_RETRIES } from "../hydrate";
+
+// ---------------------------------------------------------------------------
+// Mock data
+// ---------------------------------------------------------------------------
+
+const WORKSPACES: WorkspaceData[] = [
+  { id: "ws-1", name: "Test Workspace" } as WorkspaceData,
+];
+
+const VIEWPORT = { x: 10, y: 20, zoom: 1.5 };
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const mockApiGet = vi.mocked(api.get);
+
+/** Resolves successfully for `count` parallel workspace fetches; viewport always succeeds. */
+function succeedTimes(count: number) {
+  let workspaceRemaining = count;
+  mockApiGet.mockImplementation(async (url: string) => {
+    if (url === "/canvas/viewport") return VIEWPORT;
+    if (workspaceRemaining > 0) {
+      workspaceRemaining--;
+      return WORKSPACES;
+    }
+    throw new Error("API error");
+  });
+}
+
+/** Always fails with the given message. */
+function alwaysFail(msg = "Network error") {
+  mockApiGet.mockRejectedValue(new Error(msg));
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("hydrateCanvas", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    mockApiGet.mockReset();
+    mockHydrate.mockReset();
+    mockSetViewport.mockReset();
+  });
+
+  // ── Success on first attempt ─────────────────────────────────────────────
+
+  it("hydrates the store and returns null error on first attempt success", async () => {
+    succeedTimes(1);
+    const result = await hydrateCanvas();
+    expect(result).toEqual({ error: null });
+    expect(mockHydrate).toHaveBeenCalledOnce();
+  });
+
+  it("persists viewport when returned by the API", async () => {
+    succeedTimes(1);
+    const result = await hydrateCanvas();
+    expect(result).toEqual({ error: null });
+    expect(mockSetViewport).toHaveBeenCalledWith(VIEWPORT);
+  });
+
+  // ── Viewport failure is non-fatal ─────────────────────────────────────────
+
+  it("returns null error when viewport fetch fails but workspaces succeed", async () => {
+    mockApiGet.mockImplementation(async (url: string) => {
+      if (url === "/canvas/viewport") throw new Error("Viewport error");
+      return WORKSPACES;
+    });
+    const result = await hydrateCanvas();
+    expect(result).toEqual({ error: null });
+    expect(mockHydrate).toHaveBeenCalledOnce();
+    expect(mockSetViewport).not.toHaveBeenCalled();
+  });
+
+  // ── Retry logic ──────────────────────────────────────────────────────────
+
+  it("retries MAX_RETRIES times before returning an error", async () => {
+    alwaysFail();
+    const onRetrying = vi.fn();
+    const result = await Promise.race([
+      hydrateCanvas(onRetrying),
+      new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), 5000)),
+    ]);
+    if (result === "timeout") throw new Error("Test timed out — retries not awaited correctly");
+    expect(result.error).not.toBeNull();
+    expect(onRetrying).toHaveBeenCalledTimes(MAX_RETRIES - 1);
+  }, 10000);
+
+  it("onRetrying is called with attempt number before each retry", async () => {
+    alwaysFail();
+    const onRetrying = vi.fn();
+    await Promise.race([
+      hydrateCanvas(onRetrying),
+      new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), 5000)),
+    ]);
+    expect(onRetrying).toHaveBeenNthCalledWith(1, 1);
+    expect(onRetrying).toHaveBeenNthCalledWith(2, 2);
+  }, 10000);
+
+  it("succeeds on second attempt — hydrates after transient failure", async () => {
+    let callCount = 0;
+    mockApiGet.mockImplementation(async (url: string) => {
+      if (url === "/canvas/viewport") return null;
+      callCount++;
+      if (callCount === 1) throw new Error("Transient error");
+      return WORKSPACES;
+    });
+    const result = await Promise.race([
+      hydrateCanvas(),
+      new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), 5000)),
+    ]);
+    if (result === "timeout") throw new Error("Test timed out");
+    expect(result).toEqual({ error: null });
+    expect(mockHydrate).toHaveBeenCalledOnce();
+  }, 10000);
+
+  // ── Error messages ────────────────────────────────────────────────────────
+
+  it("error message includes the platform URL after all retries exhausted", async () => {
+    alwaysFail("Connection refused");
+    const result = await Promise.race([
+      hydrateCanvas(),
+      new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), 5000)),
+    ]);
+    if (result === "timeout") throw new Error("Test timed out");
+    expect(result.error).toContain("platform.test");
+    expect(result.error).toContain("Unable to connect");
+  }, 10000);
+
+  it("error message includes the underlying error message", async () => {
+    alwaysFail("TLS certificate expired");
+    const result = await Promise.race([
+      hydrateCanvas(),
+      new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), 5000)),
+    ]);
+    if (result === "timeout") throw new Error("Test timed out");
+    expect(result.error).not.toBeNull();
+    expect(typeof result.error).toBe("string");
+  }, 10000);
+});
@@ -282,13 +282,17 @@
 }

 .secret-row__save-btn {
-  background: #2563eb;
+  background: #1d4ed8;
  color: #ffffff;
  border: none;
  padding: 6px 12px;
  border-radius: 6px;
  font-size: 13px;
  cursor: pointer;
+  transition: background-color 0.15s;
+}
+.secret-row__save-btn:hover {
+  background: #1e40af;
 }

 .secret-row__save-btn:focus-visible {
@@ -370,13 +374,17 @@
 }

 .add-key-form__save-btn {
-  background: #2563eb;
+  background: #1d4ed8;
  color: #ffffff;
  border: none;
  padding: 8px 16px;
  border-radius: 6px;
  font-size: 13px;
  cursor: pointer;
+  transition: background-color 0.15s;
+}
+.add-key-form__save-btn:hover {
+  background: #1e40af;
 }

 .add-key-form__save-btn:focus-visible {
@@ -510,7 +518,7 @@
 .empty-state__body { font-size: 14px; color: #a1a1aa; margin: 0 0 24px; line-height: 1.5; }

 .empty-state__cta {
-  background: #2563eb;
+  background: #1d4ed8;
  color: #ffffff;
  border: none;
  padding: 10px 20px;
@@ -518,6 +526,10 @@
  font-size: 14px;
  font-weight: 500;
  cursor: pointer;
+  transition: background-color 0.15s;
+}
+.empty-state__cta:hover {
+  background: #1e40af;
 }

 .empty-state__cta:focus-visible { outline: var(--focus-ring); outline-offset: var(--focus-ring-offset); }
@@ -561,12 +573,16 @@
 .secrets-tab__error p { color: var(--status-invalid); margin: 0 0 12px; }

 .secrets-tab__refresh-btn {
-  background: #2563eb;
+  background: #1d4ed8;
  color: #ffffff;
  border: none;
  padding: 8px 16px;
  border-radius: 6px;
  cursor: pointer;
+  transition: background-color 0.15s;
+}
+.secrets-tab__refresh-btn:hover {
+  background: #1e40af;
 }

 .secrets-tab__no-results {
@@ -690,12 +706,16 @@
 }

 .guard-dialog__discard-btn {
-  background: #2563eb;
+  background: #1d4ed8;
  color: #ffffff;
  border: none;
  padding: 8px 16px;
  border-radius: 6px;
  cursor: pointer;
+  transition: background-color 0.15s;
+}
+.guard-dialog__discard-btn:hover {
+  background: #1e40af;
 }

 .guard-dialog__discard-btn:focus-visible {
@@ -747,12 +767,20 @@
 .top-bar__name { font-size: 14px; font-weight: 500; color: #d4d4d8; }

 .top-bar__btn {
-  background: #2563eb;
+  background: #1d4ed8;
  color: #ffffff;
  border: none;
  padding: 6px 12px;
  border-radius: 6px;
  font-size: 13px;
  cursor: pointer;
+  transition: background-color 0.15s;
+}
+.top-bar__btn:hover {
+  background: #1e40af;
+}
+.top-bar__btn:focus-visible {
+  outline: none;
+  box-shadow: 0 0 0 2px #18181b, 0 0 0 4px #3b82f6;
 }

@@ -22,6 +22,7 @@ Cross-links:
 """
 from __future__ import annotations

+import re
 import subprocess
 import sys
 import textwrap
@@ -542,3 +543,89 @@ def test_rule9_prod_manual_deploy_allows_rollback_control(tmp_path):
    _write(tmp_path, "ok.yml", PROD_ROLLBACK_OK)
    r = _run_lint(tmp_path)
    assert r.returncode == 0, f"stdout={r.stdout}\nstderr={r.stderr}"
+
+
+# ---------------------------------------------------------------------------
+# CI change detector fanout — workflow-only PRs keep required contexts without
+# running Go/Canvas/Python/shellcheck heavy steps.
+# ---------------------------------------------------------------------------
+
+CI_WORKFLOW = REPO_ROOT / ".gitea" / "workflows" / "ci.yml"
+CI_SURFACES = ("platform", "canvas", "python", "scripts")
+
+
+def _ci_change_patterns() -> dict[str, re.Pattern[str]]:
+    text = CI_WORKFLOW.read_text(encoding="utf-8")
+    patterns: dict[str, re.Pattern[str]] = {}
+    for surface, pattern in re.findall(
+        r'echo "(platform|canvas|python|scripts)=.*?grep -qE \'([^\']+)\'',
+        text,
+    ):
+        patterns[surface] = re.compile(pattern)
+    assert set(patterns) == set(CI_SURFACES)
+    return patterns
+
+
+def _classify_ci_change(*paths: str) -> dict[str, bool]:
+    patterns = _ci_change_patterns()
+    return {
+        surface: any(pattern.search(path) for path in paths)
+        for surface, pattern in patterns.items()
+    }
+
+
+def test_ci_change_detector_workflow_only_edits_do_not_trigger_heavy_surfaces():
+    assert _classify_ci_change(".gitea/workflows/ci.yml") == {
+        "platform": False,
+        "canvas": False,
+        "python": False,
+        "scripts": False,
+    }
+    assert _classify_ci_change(".github/workflows/ci.yml") == {
+        "platform": False,
+        "canvas": False,
+        "python": False,
+        "scripts": False,
+    }
+
+
+def test_ci_change_detector_narrow_surface_edits_only_trigger_their_surface():
+    assert _classify_ci_change("workspace-server/internal/handlers/foo.go") == {
+        "platform": True,
+        "canvas": False,
+        "python": False,
+        "scripts": False,
+    }
+    assert _classify_ci_change("canvas/app/page.tsx") == {
+        "platform": False,
+        "canvas": True,
+        "python": False,
+        "scripts": False,
+    }
+    assert _classify_ci_change("workspace/a2a_mcp_server.py") == {
+        "platform": False,
+        "canvas": False,
+        "python": True,
+        "scripts": False,
+    }
+    assert _classify_ci_change("tests/e2e/test_model_slug.sh") == {
+        "platform": False,
+        "canvas": False,
+        "python": False,
+        "scripts": True,
+    }
+
+
+def test_ci_change_detector_docs_and_meta_scripts_do_not_trigger_surfaces():
+    assert _classify_ci_change("README.md") == {
+        "platform": False,
+        "canvas": False,
+        "python": False,
+        "scripts": False,
+    }
+    assert _classify_ci_change(".gitea/scripts/lint-workflow-yaml.py") == {
+        "platform": False,
+        "canvas": False,
+        "python": False,
+        "scripts": False,
+    }
@@ -12,12 +12,14 @@ Environment variables (set by the workspace container):
  PLATFORM_URL  — platform API base URL (e.g. http://platform:8080)
 """

+import argparse
 import asyncio
 import json
 import logging
 import os
 import stat
 import sys
+import uuid
 from typing import Callable

 # Top-level (not inside main()) so the wheel rewriter expands this to
@@ -825,24 +827,163 @@ async def main():  # pragma: no cover
            break


-def cli_main() -> None:  # pragma: no cover
-    """Synchronous wrapper around the async MCP stdio loop.
+# --- HTTP/SSE Transport (for Hermes runtime) ---
+
+# Per-connection pending request queue.
+# Maps connection-id → asyncio.Queue of JSON-RPC responses.
+_http_connection_queues: dict[str, asyncio.Queue] = {}
+_http_connection_lock = asyncio.Lock()
+
+
+async def _handle_http_mcp(request) -> dict | None:
+    """Handle an incoming JSON-RPC request over HTTP. Returns the JSON-RPC response dict, or None for notifications."""
+    try:
+        body = await request.json()
+    except Exception:
+        return {"jsonrpc": "2.0", "id": None, "error": {"code": -32700, "message": "Parse error"}}
+
+    req_id = body.get("id")
+    method = body.get("method", "")
+
+    if method == "initialize":
+        return {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "result": _build_initialize_result(),
+        }
+    elif method == "notifications/initialized":
+        return None  # No response needed
+    elif method == "tools/list":
+        return {"jsonrpc": "2.0", "id": req_id, "result": {"tools": TOOLS}}
+    elif method == "tools/call":
+        params = body.get("params", {})
+        tool_name = params.get("name", "")
+        tool_args = params.get("arguments", {})
+        result_text = await handle_tool_call(tool_name, tool_args)
+        return {
+            "jsonrpc": "2.0",
+            "id": req_id,
+            "result": {"content": [{"type": "text", "text": result_text}]},
+        }
+    else:
+        return {"jsonrpc": "2.0", "id": req_id, "error": {"code": -32601, "message": f"Method not found: {method}"}}
+
+
+async def _run_http_server(port: int) -> None:
+    """Run MCP server over HTTP/SSE — compatible with Hermes MCP-native agents."""
+    try:
+        from starlette.applications import Starlette  # noqa: F401
+        from starlette.routing import Route  # noqa: F401
+        from starlette.responses import JSONResponse, Response, StreamingResponse  # noqa: F401
+    except ImportError:
+        logger.error("HTTP transport requires starlette — install with: pip install starlette uvicorn")
+        return
+
+    # Import uvicorn here so the stdio path (the common case) doesn't pay
+    # the import cost if starlette/uvicorn aren't installed.
+    import uvicorn  # noqa: F401
+
+    _http_connection_queues.clear()
+
+    async def mcp_handler(request):
+        """POST /mcp — receive and process JSON-RPC requests."""
+        conn_id = request.headers.get("x-mcp-conn-id", "default")
+        response = await _handle_http_mcp(request)
+        if response is None:
+            return Response(status_code=202)
+        async with _http_connection_lock:
+            queue = _http_connection_queues.get(conn_id)
+        if queue is not None and not queue.full():
+            await queue.put(response)
+            return Response(status_code=202)
+        # No SSE subscriber — return JSON directly
+        return JSONResponse(response)
+
+    async def sse_handler(request):
+        """GET /mcp/stream — SSE stream for push-based responses."""
+        conn_id = str(uuid.uuid4())
+        queue: asyncio.Queue = asyncio.Queue(maxsize=100)
+        async with _http_connection_lock:
+            _http_connection_queues[conn_id] = queue
+
+        async def event_stream():
+            yield f"event: connected\ndata: {json.dumps({'conn_id': conn_id})}\n\n"
+            try:
+                while True:
+                    response = await asyncio.wait_for(queue.get(), timeout=300)
+                    yield f"event: message\ndata: {json.dumps(response)}\n\n"
+                    if queue.empty():
+                        yield "event: heartbeat\ndata: null\n\n"
+            except asyncio.TimeoutError:
+                pass
+            finally:
+                async with _http_connection_lock:
+                    _http_connection_queues.pop(conn_id, None)
+
+        return StreamingResponse(
+            event_stream(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    async def health_handler(_request):
+        return JSONResponse({"ok": True, "transport": "http+sse", "port": port})
+
+    app = Starlette(
+        routes=[
+            Route("/mcp", mcp_handler, methods=["POST"]),
+            Route("/mcp/stream", sse_handler, methods=["GET"]),
+            Route("/health", health_handler),
+        ]
+    )
+    config = uvicorn.Config(app, host="127.0.0.1", port=port, log_level="warning")
+    server = uvicorn.Server(config)
+    logger.info(f"A2A MCP HTTP server listening on http://127.0.0.1:{port}/mcp")
+    await server.serve()
+
+
+def cli_main(transport: str = "stdio", port: int = 9100) -> None:  # pragma: no cover
+    """Synchronous wrapper — selects stdio or HTTP transport.

    Called by ``mcp_cli.main`` (the ``molecule-mcp`` console-script
    entry point in scripts/build_runtime_package.py) AFTER env
    validation and the standalone register + heartbeat thread setup.
    Direct callers (in-container code that already validated env and
-    runs heartbeat.py separately) can also invoke this — it's the
-    smallest possible "run the MCP stdio JSON-RPC loop" surface.
+    runs heartbeat.py separately) can also invoke this.

    Wheel-smoke gates in scripts/wheel_smoke.py pin the importability
    of this name (alongside ``mcp_cli.main``) so a silent rename can't
    break every external-runtime operator's MCP install — the 0.1.16
    ``main_sync`` rename incident is the cautionary precedent.
+
+    Args:
+        transport: "stdio" (default) or "http" (HTTP+SSE for Hermes).
+        port: TCP port for HTTP transport (default 9100).
    """
-    _warn_if_stdio_not_pipe()
-    asyncio.run(main())
+    if transport == "http":
+        asyncio.run(_run_http_server(port))
+    else:
+        _warn_if_stdio_not_pipe()
+        asyncio.run(main())


 if __name__ == "__main__":  # pragma: no cover
-    cli_main()
+    parser = argparse.ArgumentParser(description="A2A MCP Server")
+    parser.add_argument(
+        "--transport",
+        default="stdio",
+        choices=["stdio", "http"],
+        help="Transport mode: stdio (default) or http (HTTP+SSE for Hermes)",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=9100,
+        help="TCP port for HTTP transport (default 9100)",
+    )
+    args = parser.parse_args()
+    cli_main(transport=args.transport, port=args.port)
@@ -0,0 +1,671 @@
+"""Tests for the HTTP/SSE transport of a2a_mcp_server.
+
+Covers:
+- _handle_http_mcp: JSON-RPC request parsing and routing
+- Starlette app routes: POST /mcp, GET /mcp/stream, GET /health
+- cli_main argparse: --transport and --port flags
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import sys
+import types
+import uuid
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import httpx
+import pytest
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+class _DummyRequest:
+    """Minimal request duck-type for _handle_http_mcp."""
+
+    def __init__(self, body_json: dict, headers: dict | None = None):
+        self._body = body_json
+        self.headers = headers or {}
+
+    async def json(self) -> dict:
+        return self._body
+
+
+# ---------------------------------------------------------------------------
+# _handle_http_mcp — unit tests (no I/O)
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_initialize():
+    """initialize method returns protocol version, capabilities, and server info."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    req = _DummyRequest({"jsonrpc": "2.0", "id": 42, "method": "initialize", "params": {}})
+    resp = await _handle_http_mcp(req)
+
+    assert resp["jsonrpc"] == "2.0"
+    assert resp["id"] == 42
+    assert "protocolVersion" in resp["result"]
+    assert "capabilities" in resp["result"]
+    assert resp["result"]["serverInfo"]["name"] == "molecule"
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_notifications_initialized_returns_none():
+    """notifications/initialized is a notification (no response needed)."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    req = _DummyRequest({"jsonrpc": "2.0", "method": "notifications/initialized"})
+    resp = await _handle_http_mcp(req)
+
+    assert resp is None
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_tools_list():
+    """tools/list returns the TOOLS schema."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    req = _DummyRequest({"jsonrpc": "2.0", "id": 7, "method": "tools/list"})
+    resp = await _handle_http_mcp(req)
+
+    assert resp["jsonrpc"] == "2.0"
+    assert resp["id"] == 7
+    assert "tools" in resp["result"]
+    assert isinstance(resp["result"]["tools"], list)
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_unknown_method_returns_error():
+    """Unknown method returns -32601 Method not found."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    req = _DummyRequest({"jsonrpc": "2.0", "id": 3, "method": "foobar", "params": {}})
+    resp = await _handle_http_mcp(req)
+
+    assert resp["jsonrpc"] == "2.0"
+    assert resp["id"] == 3
+    assert resp["error"]["code"] == -32601
+    assert "Method not found" in resp["error"]["message"]
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_malformed_json_returns_parse_error():
+    """Request with bad JSON returns -32700 parse error."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    req = _DummyRequest.__new__(_DummyRequest)
+    req.headers = {}
+    req.json = AsyncMock(side_effect=ValueError("bad json"))
+
+    resp = await _handle_http_mcp(req)
+
+    assert resp["error"]["code"] == -32700
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_tools_call_with_get_workspace_info():
+    """tools/call for get_workspace_info returns workspace info (mocked platform call)."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    with patch("a2a_mcp_server.tool_get_workspace_info", AsyncMock(return_value="mocked info")):
+        req = _DummyRequest({
+            "jsonrpc": "2.0",
+            "id": 9,
+            "method": "tools/call",
+            "params": {"name": "get_workspace_info", "arguments": {}},
+        })
+        resp = await _handle_http_mcp(req)
+
+    assert resp["jsonrpc"] == "2.0"
+    assert resp["id"] == 9
+    assert resp["result"]["content"][0]["text"] == "mocked info"
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_tools_call_unknown_tool():
+    """tools/call for an unknown tool returns the handle_tool_call error text."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    req = _DummyRequest({
+        "jsonrpc": "2.0",
+        "id": 11,
+        "method": "tools/call",
+        "params": {"name": "not_a_real_tool", "arguments": {}},
+    })
+    resp = await _handle_http_mcp(req)
+
+    assert resp["jsonrpc"] == "2.0"
+    assert resp["id"] == 11
+    assert "Unknown tool" in resp["result"]["content"][0]["text"]
+
+
+# ---------------------------------------------------------------------------
+# Starlette app — integration tests with TestClient
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture()
+def _clear_http_globals():
+    """Reset module-level HTTP state before and after each test."""
+    import a2a_mcp_server
+
+    # Save and restore globals
+    saved_queues = a2a_mcp_server._http_connection_queues.copy()
+    saved_lock = a2a_mcp_server._http_connection_lock
+    a2a_mcp_server._http_connection_queues.clear()
+    yield
+    # Restore
+    a2a_mcp_server._http_connection_queues = saved_queues
+
+
+
+
+
+def _register_sse_queue():
+    """Register a queue for SSE push delivery (synchronous — callable from tests)."""
+    conn_id = str(uuid.uuid4())
+    queue = asyncio.Queue(maxsize=100)
+    import a2a_mcp_server
+    a2a_mcp_server._http_connection_queues[conn_id] = queue
+    return conn_id, queue
+
+
+def _build_test_app(port: int = 9100):
+    """Build the Starlette app for testing without starting a real server.
+
+    Mirrors the app construction inside _run_http_server, but returns
+    the app directly so TestClient can drive it without binding a port.
+    """
+    from starlette.applications import Starlette
+    from starlette.routing import Route
+
+    import a2a_mcp_server
+
+    async def mcp_handler(request):
+        conn_id = request.headers.get("x-mcp-conn-id", "default")
+        response = await a2a_mcp_server._handle_http_mcp(request)
+        if response is None:
+            from starlette.responses import Response
+            return Response(status_code=202)
+        async with a2a_mcp_server._http_connection_lock:
+            queue = a2a_mcp_server._http_connection_queues.get(conn_id)
+        if queue is not None and not queue.full():
+            await queue.put(response)
+            from starlette.responses import Response
+            return Response(status_code=202)
+        from starlette.responses import JSONResponse
+        return JSONResponse(response)
+
+    async def sse_handler(request):
+        conn_id, queue = _register_sse_queue()
+
+        import asyncio as _asyncio
+
+        async def event_stream():
+            import json as _json
+            yield f"event: connected\ndata: {_json.dumps({'conn_id': conn_id})}\n\n"
+            try:
+                while True:
+                    response = await _asyncio.wait_for(queue.get(), timeout=300)
+                    import json as _json
+                    yield f"event: message\ndata: {_json.dumps(response)}\n\n"
+                    if queue.empty():
+                        yield "event: heartbeat\ndata: null\n\n"
+            except _asyncio.TimeoutError:
+                pass
+            finally:
+                async with a2a_mcp_server._http_connection_lock:
+                    a2a_mcp_server._http_connection_queues.pop(conn_id, None)
+
+        from starlette.responses import StreamingResponse
+        return StreamingResponse(
+            event_stream(),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache",
+                "Connection": "keep-alive",
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    async def health_handler(_request):
+        from starlette.responses import JSONResponse
+        return JSONResponse({"ok": True, "transport": "http+sse", "port": port})
+
+    return Starlette(
+        routes=[
+            Route("/mcp", mcp_handler, methods=["POST"]),
+            Route("/mcp/stream", sse_handler, methods=["GET"]),
+            Route("/health", health_handler),
+        ]
+    )
+
+
+class TestHTTPAppRoutes:
+    """Integration tests using Starlette TestClient against the HTTP app.
+
+    Starlette TestClient uses the ASGI interface directly (no real HTTP server
+    or uvicorn needed), so no uvicorn mock is required.
+    """
+
+    def test_health_returns_ok_and_transport(self, _clear_http_globals):
+        from starlette.testclient import TestClient
+
+        app = _build_test_app(port=9100)
+        with TestClient(app) as client:
+            resp = client.get("/health")
+
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["ok"] is True
+        assert data["transport"] == "http+sse"
+        assert data["port"] == 9100
+
+    def test_health_accepts_different_port(self, _clear_http_globals):
+        from starlette.testclient import TestClient
+
+        app = _build_test_app(port=9999)
+        with TestClient(app) as client:
+            resp = client.get("/health")
+
+        assert resp.json()["port"] == 9999
+
+    def test_mcp_post_initialize(self, _clear_http_globals):
+        from starlette.testclient import TestClient
+
+        app = _build_test_app()
+        with TestClient(app) as client:
+            resp = client.post("/mcp", json={
+                "jsonrpc": "2.0",
+                "id": 1,
+                "method": "initialize",
+                "params": {},
+            })
+
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["id"] == 1
+        assert "protocolVersion" in data["result"]
+
+    def test_mcp_post_tools_list(self, _clear_http_globals):
+        from starlette.testclient import TestClient
+
+        app = _build_test_app()
+        with TestClient(app) as client:
+            resp = client.post("/mcp", json={
+                "jsonrpc": "2.0",
+                "id": 2,
+                "method": "tools/list",
+                "params": {},
+            })
+
+        assert resp.status_code == 200
+        data = resp.json()
+        assert "tools" in data["result"]
+        assert len(data["result"]["tools"]) > 0
+
+    def test_mcp_post_notifications_initialized_returns_202(self, _clear_http_globals):
+        from starlette.testclient import TestClient
+
+        app = _build_test_app()
+        with TestClient(app) as client:
+            resp = client.post("/mcp", json={
+                "jsonrpc": "2.0",
+                "method": "notifications/initialized",
+            })
+
+        # Notifications return 202 with no body
+        assert resp.status_code == 202
+
+    def test_mcp_post_unknown_method_returns_200_with_error(self, _clear_http_globals):
+        from starlette.testclient import TestClient
+
+        app = _build_test_app()
+        with TestClient(app) as client:
+            resp = client.post("/mcp", json={
+                "jsonrpc": "2.0",
+                "id": 5,
+                "method": "no_such_method",
+                "params": {},
+            })
+
+        assert resp.status_code == 200
+        data = resp.json()
+        assert data["error"]["code"] == -32601
+
+    def test_mcp_post_malformed_json_returns_error(self, _clear_http_globals):
+        """Malformed JSON body returns a JSON-RPC parse-error response (HTTP 200)."""
+        from starlette.testclient import TestClient
+
+        app = _build_test_app()
+        with TestClient(app, raise_server_exceptions=False) as client:
+            resp = client.post(
+                "/mcp",
+                content=b"not json at all",
+                headers={"Content-Type": "application/json"},
+            )
+        # _handle_http_mcp catches ValueError from request.json() and returns
+        # a JSON-RPC parse-error response with HTTP 200.
+        assert resp.status_code == 200
+        assert resp.json()["error"]["code"] == -32700
+        assert "Parse error" in resp.json()["error"]["message"]
+
+    @pytest.mark.asyncio()
+    async def test_sse_stream_populates_queue(self, _clear_http_globals):
+        """_register_sse_queue adds a queue to _http_connection_queues before any async work."""
+        import a2a_mcp_server
+
+        conn_id, queue = _register_sse_queue()
+
+        # The queue is registered synchronously — no await needed, no cleanup ran yet.
+        assert conn_id in a2a_mcp_server._http_connection_queues
+        assert len(conn_id) == 36  # valid UUID format
+        assert not queue.full()
+
+    @pytest.mark.asyncio()
+    async def test_sse_queue_delivers_response(self, _clear_http_globals):
+        """POST /mcp with x-mcp-conn-id routes response into the SSE queue."""
+        import uuid
+
+        import a2a_mcp_server
+        from starlette.testclient import TestClient
+
+        # Pre-register an SSE queue to simulate an active SSE subscriber
+        conn_id = str(uuid.uuid4())
+        queue: asyncio.Queue = asyncio.Queue(maxsize=100)
+        async with a2a_mcp_server._http_connection_lock:
+            a2a_mcp_server._http_connection_queues[conn_id] = queue
+
+        # POST a tools/call with the conn_id header
+        with TestClient(_build_test_app()) as client:
+            with patch("a2a_mcp_server.tool_get_workspace_info", AsyncMock(return_value="test-ws-info")):
+                resp = client.post(
+                    "/mcp",
+                    headers={"x-mcp-conn-id": conn_id},
+                    json={
+                        "jsonrpc": "2.0",
+                        "id": 99,
+                        "method": "tools/call",
+                        "params": {"name": "get_workspace_info", "arguments": {}},
+                    },
+                )
+
+        # The handler returns 202 because the response was queued for SSE delivery
+        assert resp.status_code == 202
+
+        # Verify the response was placed in the SSE queue
+        result = await asyncio.wait_for(queue.get(), timeout=2.0)
+        assert result["id"] == 99
+        assert result["result"]["content"][0]["text"] == "test-ws-info"
+
+
+# ---------------------------------------------------------------------------
+# handle_tool_call — remaining tool branches
+# ---------------------------------------------------------------------------
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_tools_call_send_message_to_user_with_mixed_attachments():
+    """attachments with non-string elements are filtered; the list branch is exercised."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    with patch("a2a_mcp_server.tool_send_message_to_user", AsyncMock(return_value="sent ok")) as mock_fn:
+        req = _DummyRequest({
+            "jsonrpc": "2.0",
+            "id": 21,
+            "method": "tools/call",
+            "params": {
+                "name": "send_message_to_user",
+                "arguments": {
+                    "message": "hello",
+                    # Mixed types: list contains a dict (non-string) and an empty string
+                    "attachments": [{"url": "http://x"}, "", "valid.zip", None],
+                },
+            },
+        })
+        resp = await _handle_http_mcp(req)
+
+    assert resp["result"]["content"][0]["text"] == "sent ok"
+    # Only string, non-empty values passed through
+    mock_fn.assert_called_once()
+    _, kwargs = mock_fn.call_args
+    assert kwargs["attachments"] == ["valid.zip"]
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_tools_call_wait_for_message():
+    """wait_for_message is dispatched and returns the wrapped result."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    with patch("a2a_mcp_server.tool_wait_for_message", AsyncMock(return_value="no messages")):
+        req = _DummyRequest({
+            "jsonrpc": "2.0",
+            "id": 22,
+            "method": "tools/call",
+            "params": {"name": "wait_for_message", "arguments": {"timeout_secs": 5.0}},
+        })
+        resp = await _handle_http_mcp(req)
+
+    assert resp["result"]["content"][0]["text"] == "no messages"
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_tools_call_inbox_peek():
+    """inbox_peek is dispatched with the limit argument."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    with patch("a2a_mcp_server.tool_inbox_peek", AsyncMock(return_value="2 items")):
+        req = _DummyRequest({
+            "jsonrpc": "2.0",
+            "id": 23,
+            "method": "tools/call",
+            "params": {"name": "inbox_peek", "arguments": {"limit": 5}},
+        })
+        resp = await _handle_http_mcp(req)
+
+    assert resp["result"]["content"][0]["text"] == "2 items"
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_tools_call_inbox_pop():
+    """inbox_pop is dispatched with the activity_id argument."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    with patch("a2a_mcp_server.tool_inbox_pop", AsyncMock(return_value="acked")):
+        req = _DummyRequest({
+            "jsonrpc": "2.0",
+            "id": 24,
+            "method": "tools/call",
+            "params": {"name": "inbox_pop", "arguments": {"activity_id": "abc-123"}},
+        })
+        resp = await _handle_http_mcp(req)
+
+    assert resp["result"]["content"][0]["text"] == "acked"
+
+
+@pytest.mark.asyncio()
+async def test_handle_http_mcp_tools_call_chat_history():
+    """chat_history is dispatched with peer_id, limit, and before_ts arguments."""
+    from a2a_mcp_server import _handle_http_mcp
+
+    with patch("a2a_mcp_server.tool_chat_history", AsyncMock(return_value="history")):
+        req = _DummyRequest({
+            "jsonrpc": "2.0",
+            "id": 25,
+            "method": "tools/call",
+            "params": {
+                "name": "chat_history",
+                "arguments": {"peer_id": "ws-peer-1", "limit": 10, "before_ts": ""},
+            },
+        })
+        resp = await _handle_http_mcp(req)
+
+    assert resp["result"]["content"][0]["text"] == "history"
+
+
+# ---------------------------------------------------------------------------
+# cli_main argparse — unit tests
+# ---------------------------------------------------------------------------
+
+
+def test_mcp_post_falls_back_to_json_when_sse_queue_is_full(_clear_http_globals):
+    """When the SSE queue is full (>100 pending), the handler returns JSON directly."""
+    import a2a_mcp_server
+    from starlette.testclient import TestClient
+
+    # Pre-register a queue and fill it to capacity
+    conn_id = str(uuid.uuid4())
+    queue: asyncio.Queue = asyncio.Queue(maxsize=2)  # small queue for testing
+
+    async def _setup():
+        async with a2a_mcp_server._http_connection_lock:
+            a2a_mcp_server._http_connection_queues[conn_id] = queue
+        queue.put_nowait({"id": 1})
+        queue.put_nowait({"id": 2})
+
+    _sync_run(_setup())
+    assert queue.full()
+
+    app = _build_test_app()
+    with TestClient(app) as client:
+        resp = client.post(
+            "/mcp",
+            headers={"x-mcp-conn-id": conn_id},
+            json={"jsonrpc": "2.0", "id": 99, "method": "initialize", "params": {}},
+        )
+
+    # With a full queue, the handler returns the response as JSON (not 202)
+    assert resp.status_code == 200
+    assert resp.json()["id"] == 99
+    assert "result" in resp.json()
+
+
+def _sync_run(coro):
+    """Run a coroutine synchronously for test isolation (no real event loop needed)."""
+    try:
+        loop = asyncio.new_event_loop()
+        asyncio.set_event_loop(loop)
+        try:
+            return loop.run_until_complete(coro)
+        finally:
+            loop.close()
+    except Exception:
+        raise
+
+
+def test_cli_main_transport_stdio_calls_main(monkeypatch):
+    """cli_main(transport='stdio') calls asyncio.run(main) without HTTP."""
+    import a2a_mcp_server
+
+    run_calls: list = []
+
+    async def fake_main():
+        run_calls.append("called")
+
+    monkeypatch.setattr(a2a_mcp_server, "main", fake_main)
+    monkeypatch.setattr(a2a_mcp_server.asyncio, "run", _sync_run)
+    monkeypatch.setattr(a2a_mcp_server, "_assert_stdio_is_pipe_compatible", lambda: None)
+
+    a2a_mcp_server.cli_main(transport="stdio", port=9100)
+
+    assert "called" in run_calls
+
+
+def test_cli_main_transport_http_calls_run_http_server(monkeypatch):
+    """cli_main(transport='http') calls _run_http_server without stdio."""
+    import a2a_mcp_server
+
+    run_http_calls = []
+
+    async def fake_run_http(port):
+        run_http_calls.append(port)
+
+    # asyncio.run must execute the coroutine for _run_http_server to be called
+    monkeypatch.setattr(a2a_mcp_server.asyncio, "run", _sync_run)
+    monkeypatch.setattr(a2a_mcp_server, "_run_http_server", fake_run_http)
+    # stdio path must not be entered
+    monkeypatch.setattr(a2a_mcp_server, "_assert_stdio_is_pipe_compatible", lambda: None)
+
+    a2a_mcp_server.cli_main(transport="http", port=9102)
+
+    assert run_http_calls == [9102]
+
+
+def test_cli_main_http_skips_stdio_check(monkeypatch):
+    """When transport=http, _assert_stdio_is_pipe_compatible must NOT be called."""
+    import a2a_mcp_server
+
+    called = []
+
+    def fake_assert():
+        called.append("assert_called")
+
+    # Patch on the module object directly
+    monkeypatch.setattr(a2a_mcp_server, "_assert_stdio_is_pipe_compatible", fake_assert)
+    monkeypatch.setattr(a2a_mcp_server.asyncio, "run", lambda fn: None)
+
+    a2a_mcp_server.cli_main(transport="http", port=9100)
+
+    assert "assert_called" not in called
+
+
+def test_cli_main_default_transport_is_stdio(monkeypatch):
+    """cli_main() with no args defaults to stdio transport."""
+    import a2a_mcp_server
+
+    called_as: list = []
+
+    async def fake_main():
+        called_as.append("called")
+
+    monkeypatch.setattr(a2a_mcp_server, "main", fake_main)
+    monkeypatch.setattr(a2a_mcp_server.asyncio, "run", _sync_run)
+    monkeypatch.setattr(a2a_mcp_server, "_assert_stdio_is_pipe_compatible", lambda: None)
+
+    a2a_mcp_server.cli_main()  # No args — defaults to stdio
+
+    assert "called" in called_as
+
+
+def test_cli_main_main_raises_propagates(monkeypatch):
+    """If main() raises, cli_main() re-raises (doesn't swallow)."""
+    import a2a_mcp_server
+
+    async def fake_main():
+        raise RuntimeError("boom")
+
+    monkeypatch.setattr(a2a_mcp_server, "main", fake_main)
+    monkeypatch.setattr(a2a_mcp_server.asyncio, "run", _sync_run)
+    monkeypatch.setattr(a2a_mcp_server, "_assert_stdio_is_pipe_compatible", lambda: None)
+
+    with pytest.raises(RuntimeError, match="boom"):
+        a2a_mcp_server.cli_main(transport="stdio")
+
+
+# ---------------------------------------------------------------------------
+# uvicorn/starlette lazy-import
+# ---------------------------------------------------------------------------
+
+
+def test_run_http_server_is_coroutine_function():
+    """_run_http_server is a coroutine function accepting a port argument."""
+    import inspect
+    from a2a_mcp_server import _run_http_server
+
+    assert inspect.iscoroutinefunction(_run_http_server)
+
+
+def test_run_http_server_signature_port_int():
+    """_run_http_server accepts port as int."""
+    import inspect
+    from a2a_mcp_server import _run_http_server
+
+    sig = inspect.signature(_run_http_server)
+    assert "port" in sig.parameters
+    assert sig.parameters["port"].annotation == int
@@ -0,0 +1,107 @@
+"""Test coverage for builtin_tools.security._redact_secrets().
+
+Issue #834 (C2): commit_memory must not persist API keys verbatim.
+
+Pre-commit hook blocks bare secret-like strings (ghp_, sk-ant-, etc.) to prevent
+accidental commits of real credentials.  These tests focus on the functional
+behaviour of the redaction logic: idempotency, contextual keyword=value patterns,
+boundary cases, and mixed content — without triggering the hook's length thresholds.
+The pre-commit hook itself is the primary guard for bare-pattern detection.
+"""
+from __future__ import annotations
+
+from builtin_tools.security import REDACTED, _redact_secrets
+
+
+class TestRedactContextual:
+    """Keyword=value patterns with high-entropy values (under pre-commit threshold)."""
+
+    def test_api_key_contextual(self):
+        """api_key=X where X ≥ 40 base64 chars → value replaced, keyword preserved."""
+        value = "A" * 40
+        assert _redact_secrets(f"api_key={value}") == f"api_key={REDACTED}"
+
+    def test_keyword_contextual(self):
+        """Generic 'key=' also matches."""
+        value = "B" * 45
+        assert _redact_secrets(f"key={value}") == f"key={REDACTED}"
+
+    def test_secret_contextual(self):
+        value = "C" * 50
+        assert _redact_secrets(f"secret= {value}") == f"secret= {REDACTED}"
+
+    def test_token_contextual(self):
+        value = "D" * 40
+        assert _redact_secrets(f"token={value}") == f"token={REDACTED}"
+
+    def test_password_contextual(self):
+        value = "E" * 50
+        assert _redact_secrets(f"password={value}") == f"password={REDACTED}"
+
+    def test_keyword_spacing_tolerated(self):
+        """Spaces around = are tolerated by the pattern."""
+        value = "F" * 40
+        assert _redact_secrets(f"key = {value}") == f"key = {REDACTED}"
+
+    def test_contextual_too_short_not_redacted(self):
+        """Value shorter than 40 chars is not redacted."""
+        short = "A" * 39
+        assert _redact_secrets(f"api_key={short}") == f"api_key={short}"
+
+    def test_case_insensitive_keyword(self):
+        """Keyword matching is case-insensitive."""
+        value = "G" * 40
+        assert _redact_secrets(f"API_KEY={value}") == f"API_KEY={REDACTED}"
+        assert _redact_secrets(f"Token={value}") == f"Token={REDACTED}"
+        assert _redact_secrets(f"SECRET={value}") == f"SECRET={REDACTED}"
+
+    def test_boundary_preserved(self):
+        """Contextual pattern preserves the keyword; only value is replaced."""
+        value = "H" * 40
+        result = _redact_secrets(f"api_key={value}")
+        assert result.startswith("api_key=")
+        assert result.endswith(REDACTED)
+        assert result == f"api_key={REDACTED}"
+
+    def test_base64_chars_in_value(self):
+        """Base64 alphabet chars (/ +) in value are covered by the charset."""
+        # 40-char string with base64 chars
+        value = "A" * 20 + "/+" + "A" * 18
+        result = _redact_secrets(f"api_key={value}")
+        assert result == f"api_key={REDACTED}"
+
+
+class TestRedactEdgeCases:
+    """Non-secret strings, idempotency, and boundary conditions."""
+
+    def test_idempotent(self):
+        """Calling redaction twice produces the same result."""
+        text = f"token={'A' * 40}"
+        first = _redact_secrets(text)
+        second = _redact_secrets(first)
+        assert second == first
+        assert REDACTED in first
+
+    def test_already_redacted_string(self):
+        """The [REDACTED] sentinel itself is not matched by any pattern."""
+        assert _redact_secrets(f"see {REDACTED} here") == f"see {REDACTED} here"
+
+    def test_no_match_passthrough(self):
+        """Normal prose passes through unchanged."""
+        assert _redact_secrets("The answer is 42.") == "The answer is 42."
+        assert _redact_secrets("Hello, world!") == "Hello, world!"
+        assert _redact_secrets("api_key short") == "api_key short"
+        assert _redact_secrets("") == ""
+
+    def test_empty_string(self):
+        assert _redact_secrets("") == ""
+
+    def test_short_value_not_secret(self):
+        """A short string after a keyword= prefix is not a secret."""
+        assert _redact_secrets("token=short") == "token=short"
+
+    def test_mixed_content(self):
+        """Real text with a secret-like prefix → only the secret is redacted."""
+        value = "A" * 40
+        result = _redact_secrets(f"found secret: api_key={value} in config")
+        assert result == f"found secret: api_key={REDACTED} in config"