feat(mcp): detect Connected-but-namespaces-missing attachment failures (Closes #708)

docs/mcp-namespace-health.md

@@ -86,3 +86,26 @@ When a namespace returns EOF, follow
 
 When blocked, repair the IDE namespace and re-record a healthy
 `client_namespace` assessment before retrying the mutation.
+
+## Connected vs Attached Tool Surface (#708)
+
+MCP servers can report **Connected** at the CLI / host inventory layer while the **active LLM session exposes none of their tool namespaces**.
+
+### Core principle
+
+* **Connected status at host layer ≠ attached tools in active session.**
+* Required preflight proof is **live tool visibility + `gitea_whoami` call** through the target namespace, not host `Connected` status alone.
+* When servers report Connected but namespaces are absent from attached tools, classify as `mcp_connected_namespaces_missing`.
+
+### Forbidden unsafe fallbacks
+
+When `mcp_connected_namespaces_missing` is detected, workflows must **fail closed** and must **never** encourage or perform:
+
+* direct imports of MCP server Python modules
+* CLI or raw Gitea API mutations as a substitute for native tools
+* profile hopping to another MCP profile/namespace to bypass the empty session
+* session-state overrides or hand-edited session/ledger files
+* process kills (`pkill`), config mtime touches, or `.env` edits
+
+Only sanctioned recovery: **client reconnect path**, followed by full preflight (`whoami` → capability resolve → task).
+